Troubleshooting

Fix the common bumps: connection, scripts, Web UI auth. Start with the quick checks below.

Quick checks first

Photoshop is installed and open — the server can launch it, but an open instance rules out half the causes.
Your MCP client config points at the right server — compare it with the snippet in Getting started.
Web UI tabs: reload from the exact URL the CLI printed — a tab kept open across a server restart carries a stale token.

Common issues

“Photoshop not found”

Cause: Photoshop is not in the default install location, so the server can't find the binary.

Fix:

Make sure Photoshop is installed in the default location, or point the server at a custom path with PHOTOSHOP_PATH in your client config:

mcp config

{
  "env": {
    "PHOTOSHOP_PATH": "C:\\Custom\\Path\\Adobe Photoshop 2025\\Photoshop.exe"
  }
}

“Failed to connect to Photoshop”

Cause: Photoshop is not running, or scripting is blocked.

Fix:

Make sure Photoshop is running — the server tries to launch it, but a running instance connects faster and more reliably.
Check that scripting is enabled in Photoshop preferences.
On Windows, verify COM automation is not blocked by security settings.

Web UI: 401 unauthorized from /api/*

Cause: Every /api/* request must present the session token generated when the UI server starts. The browser gets it automatically; old tabs and external scripts don't.

Fix:

In the browser: reload the page from the URL printed by photoshop-mcp-ui.
From a script: read the token from ~/.photoshop-mcp/ui-session.json and send it as a header:

terminal

TOKEN=$(node -p "require('$HOME/.photoshop-mcp/ui-session.json').token")
curl -H "x-psmcp-token: $TOKEN" http://127.0.0.1:5174/api/status

Authorization: Bearer <token> works too. Set PSMCP_UI_TOKEN before starting the server to pin a known token.

Web UI: 403 invalid_host or invalid_origin

Cause: Two guards run before the token check: invalid_host means the Host header did not resolve to the loopback address on the server's port (this blocks DNS rebinding); invalid_origin means the request came from a different origin than the UI itself.

Fix:

Open the UI through the exact URL the CLI printed (http://127.0.0.1:<port>) — not a hostname that merely points at your machine, and not from a page served on another port.

photoshop_execute_script returns “Result: undefined”

Cause: ExtendScript runs inside a server-side IIFE wrapper. Without an explicit return, the block evaluates to undefined — side effects (layer renames, property changes) may still have applied.

Fix:

Add an explicit return to your script:

photoshop_execute_script

photoshop_execute_script({
  code: `
    app.activeDocument.activeLayer.name = "Updated";
    return { ok: true };
  `
})

See the photoshop_execute_script section in Available tools for details.

“Script execution timeout”

Cause: The default timeout is 30 seconds, and large documents can push operations past it.

Fix:

Break complex operations into smaller steps and run them in sequence.

Web UI: CLI account auth

Symptoms when using the Claude Code / Gemini CLI account mode in the Web UI.

Symptom	Likely cause	Fix
cli_not_found	Claude Code / Gemini CLI not installed	npm i -g @anthropic-ai/claude-code or npm i -g @google/gemini-cli
not_authenticated	No CLI OAuth session (API key / SDK auth does not count)	Run claude auth login or gemini auth login in Terminal, or switch to API key auth
SDK client works, UI CLI mode fails	SDK/API credentials are separate from CLI OAuth	Use API key in the Web UI, or log in with claude auth login for CLI mode
claude / gemini not on PATH	Custom install location	Settings → CLI path → Check connection
Chat works in IDE but not UI (CLI mode)	OAuth tokens are CLI-only	Use CLI account in the UI; API keys and CLI sessions are separate
Gemini multi-turn feels forgetful	Headless CLI may start a fresh session each turn	Known limitation; history is prepended to the prompt (MVP)

Debug logging

Enable detailed logging with LOG_LEVEL=0 in your client config:

mcp config

{
  "env": {
    "LOG_LEVEL": "0"
  }
}

Still stuck?

Search existing issues or open a new one — logs captured with debug logging help a lot.

GitHub issues Community recipes