> ## Documentation Index
> Fetch the complete documentation index at: https://comfyui-mcp.artokun.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Fixes for the issues users actually hit: ComfyUI-Manager version mismatches (405s), git-URL installs being silently skipped, the panel unreachable from a remote browser, stale npx caches, and port-forwarded remotes misdetected as local.

Every entry here started life as a real bug report. If yours isn't covered,
[open an issue](https://github.com/artokun/comfyui-mcp/issues) — it'll
probably end up on this page.

## `install_custom_node` fails with `405 Method Not Allowed` for `/v2/manager/queue/task`

**Cause:** two generations of ComfyUI-Manager exist. The `/v2/manager/*` API
is the **v4 lineage** (pip package `comfyui_manager` ≥ 4.x); the **released
Manager 3.x** — what ComfyUI-Manager installs by default — serves the same
queue under different routes.

**Fix:** update to `comfyui-mcp` ≥ **0.24.3** — it auto-detects the Manager
generation per target and speaks both dialects. No Manager change needed.

**Optional but recommended — upgrade to Manager v4** for the features 3.x
can't do remotely (notably **arbitrary-URL model downloads**, which 3.x
whitelist-gates):

```bash theme={null}
# in your ComfyUI python environment
pip install -U comfyui_manager
# then remove/disable the old custom_nodes/ComfyUI-Manager clone and restart
```

The [RunPod image](./cloud-deployment) already ships Manager v4.

**Note on `useCmCli: true`:** the cm-cli fallback runs Manager's CLI as a
subprocess, so it needs the **local filesystem** — it can't work against a
remote/`--tunnel` target, and it needs `COMFYUI_PYTHON` pointed at your
ComfyUI venv's interpreter when `python` isn't on PATH. For remote targets,
the Manager HTTP path (the default) is the right mechanism.

## Custom node installed from a git URL never appears

Registry-id installs work, but a raw GitHub URL install reports success and
the pack never shows up.

**Cause:** Manager treats arbitrary-git-URL installs as high-risk and
**silently skips them** below a permissive security level (it still marks the
queue task "done"). On Manager 3.x there is additionally a dedicated
`allow_git_url_install` config flag.

**Fix:** in Manager's `config.ini` (under your ComfyUI user dir):

```ini theme={null}
[default]
security_level = weak          ; Manager v4: allows git-URL installs
allow_git_url_install = True   ; Manager 3.x: additionally required
```

Restart ComfyUI afterward. On the RunPod image this is the default as of
image `1.6` (`COMFY_SECURITY_LEVEL` env overrides it; the level is re-asserted
on every boot). Images `1.4`/`1.5` *intended* this but a baked
`COMFY_SECURITY_LEVEL=normal-` env var overrode the boot script's default —
on those images set `COMFY_SECURITY_LEVEL=weak` in the pod's environment.
Only relax this on a machine you control — it removes Manager's install
guardrails.

## RunPod: Agent Panel tab is empty — its files exist but are all 0 bytes

ComfyUI lists `comfyui-mcp-panel` but the sidebar tab never loads;
`ls -la /workspace/custom_nodes/comfyui-mcp-panel` shows every file at **0
bytes**. User-installed nodes may be empty the same way.

**Cause:** the network volume ran **out of space** at some point (often the
first-boot \~7 GB spotcheck-model copy on a small volume, or a big model
download). On ENOSPC, `cp`/`git` still *create* each file but write nothing
into it — and since the volume persists, the husks survive every redeploy.

**Fix:** free or grow the volume, then restart the pod. As of image `1.6` the
boot script warns when the volume is low/full, skips the spotcheck-model copy
when it wouldn't fit, and **self-heals** a 0-byte panel automatically (re-clone
from GitHub, or the image seed when offline). It also logs
`WARN: custom nodes with 0-byte __init__.py` naming any other broken nodes —
reinstall those via Manager. On images `<= 1.5`, delete the panel folder and
restart: `rm -rf /workspace/custom_nodes/comfyui-mcp-panel`.

## Panel says "No agent is listening on the bridge (ws\://127.0.0.1:9180)"

You're opening ComfyUI **in a browser on a different machine** than where the
orchestrator runs. The bridge is loopback-only by design, and `127.0.0.1` in
your browser is the browser's machine — not the server's.

**Fix — run the orchestrator on the machine WITH the browser** (this is the
supported topology; the agent runs on *your* machine and drives the remote
ComfyUI):

```bash theme={null}
npx -y comfyui-mcp@latest connect http://<comfyui-host>:8188
```

Then click Connect in the panel. Nothing needs to run on the ComfyUI box
besides ComfyUI + the panel custom node. For an **https** ComfyUI (RunPod
proxy), the orchestrator auto-upgrades the bridge to a secure `wss://` tunnel
— same command.

**Or run the orchestrator server-side (≥ 0.24.5)** — for a 24/7 headless box
(e.g. a standalone Ollama/OpenClaw server) where the agent should live next to
ComfyUI and browsers connect from anywhere on the LAN:

```bash theme={null}
# on the SERVER — bind the bridge on the LAN, token-gated (mandatory)
COMFYUI_MCP_BRIDGE_HOST=0.0.0.0 \
COMFYUI_MCP_BRIDGE_TOKEN=<pick-a-long-secret> \
npx -y comfyui-mcp@latest --panel-orchestrator
```

It prints a ready-to-paste `ws://<server-ip>:9180/?token=…` — put that in the
panel's **Settings → Advanced → Bridge URL** on any machine and click
Connect. A non-loopback bind **refuses to start without a token**, and every
connection is checked on the WebSocket upgrade (constant-time). Treat the URL
like a password: anyone holding it can drive the agent.

## New release is out but I'm still seeing old behavior

`npx` caches packages aggressively — `npx -y comfyui-mcp@latest` can serve a
weeks-old build from `~/.npm/_npx`.

```bash theme={null}
# clear it, then relaunch
npx clear-npx-cache
# or on Windows:
#   Remove-Item -Recurse -Force "$env:LOCALAPPDATA\npm-cache\_npx"
```

Also check the panel custom node: if it lives on a **network volume**
(`/workspace` on RunPod) from an older install, that copy shadows the
image's auto-updating one. `git -C <panel-dir> fetch && git -C <panel-dir> reset --hard origin/main`,
or reinstall `comfyui-agent-panel` from ComfyUI-Manager, then restart
ComfyUI and hard-refresh the browser tab (Ctrl+Shift+R).

## Port-forwarded remote ComfyUI is misdetected as local (dstack, SSH tunnels)

A remote ComfyUI reachable at `localhost:8188` (dstack, `ssh -L`, kubectl
port-forward) trips the loopback heuristic: comfyui-mcp assumes a local
install, enabling local-only tools against a filesystem that doesn't have
ComfyUI on it.

**Fix (≥ 0.24.1):** pass `--force-remote` (or `COMFYUI_MCP_FORCE_REMOTE=1`):

```bash theme={null}
npx -y comfyui-mcp@latest connect http://localhost:8188 --force-remote
```

Generation history for remote targets lives under
`~/.comfyui-mcp/instances/<host_port>/` (override with `COMFYUI_MCP_DATA_DIR`).

## Docker: container exits immediately in HTTP mode

Binding a non-loopback host without auth **hard-fails by design** (an open
`/mcp` endpoint on `0.0.0.0` would be exposed). Pass a token, or opt out
explicitly:

```bash theme={null}
docker run --rm -p 9100:9100 -e COMFYUI_MCP_HTTP_TOKEN=changeme comfyui-mcp \
  --http --host 0.0.0.0 --port 9100
# or (trusted networks only):
#   ... --http --host 0.0.0.0 --port 9100 --allow-unauthenticated-non-loopback
```

stdio mode (the default, what MCP clients use) needs none of this.

## The agent never calls a tool — no error, it just talks

It describes your workflow instead of reading it, or offers to write a script.
There is no error because nothing failed: either the tools never reached your
client, or your client is stopping the calls, or the capability exists under a
name that never came up. Those three look identical from the outside and have
opposite fixes, so guessing is worse than checking.

Two questions to your agent tell them apart —
see [When it says nothing](./using-tools#when-it-says-nothing). Note that a
client-side permission block never reaches this server, so nothing in the logs
below will show it.

## Local models: tool calls fail or the model "can't see" tools

* **First move: use [our fine-tuned model](./local-llms#our-fine-tuned-local-models-free-recommended)** —
  `ollama pull artokun/gemma4-comfyui-mcp:e4b` (the panel's Ollama default).
  It's Gemma 4 trained on the comfyui-mcp tool suite itself, which eliminates
  most "wrong tool / malformed args" failures out of the box (`:e2b` for
  \~2 GB VRAM, `:12b` for \~8 GB — every rung beats its stock base on the
  arena; `:e4b` remains the sweet spot).
* **gemma3 has no native tool calling in Ollama** — unsupported; use
  our fine-tune above, stock `gemma4` (e4b+), `qwen3`, or `llama3.1+`.
* Make sure [compact tool mode](./local-llms) is on for small models —
  it's the default, so this only bites if you opted into `--full`: \~200 full
  schemas overflow small contexts and the model starts hallucinating tool
  names.
* Cold model loads can take 30s+ before the first token — the panel's
  watchdog accounts for this, but a request that dies instantly usually
  means the model tag isn't pulled (`ollama pull <tag>`).
* **Every request suddenly failing / connection refused on 11434** — the
  Ollama app/daemon isn't running. Quitting the tray app kills the API with
  it, which is easy to do by accident while an agent is mid-run (the panel
  gives no warning that a local backend is in use). Relaunch the app (or
  `ollama serve`) and reconnect — sessions resume; no panel restart needed.

## Where to look for logs

* **Orchestrator**: the terminal running `connect` / `--panel-orchestrator`.
* **ComfyUI-side**: `get_system_stats (action:"logs")` MCP tool, or the pod's log stream on RunPod.
* **Panel JS**: the browser devtools console (the bridge client logs
  connect/reconnect transitions).
* **Health in one call**: the `get_system_stats (action:"health")` tool aggregates
  version/GPU/VRAM/queue/model-dirs/recent-errors.