Troubleshooting

The PS-MCP Bridge panel says "Disconnected"

Symptom: The panel inside Photoshop never connects to the server, or tools error out with a connection failure.

Fix: Confirm the MCP server is actually running (your MCP client launches it on startup). The panel retries the connection every 3 seconds on its own — no need to reopen it. If it still won't connect, restart Photoshop entirely (the panel doesn't always reload cleanly after a network or port change).

MCP client says photoshop-mcp didn't respond

Symptom: The client loads the server but then times out or says 'tool not available'.

Fix: Confirm Photoshop is open with a document loaded, and that the PS-MCP Bridge panel says \"Connected\". The server talks to Photoshop through the bridge plugin over WebSocket — without the app, a document, or the panel connected, tools error out. Then restart the MCP client.

Invalid license error

Symptom: Client logs say 'license validation failed' or 'PS_MCP_LICENSE not set'.

Fix: The license in your config doesn't match the one on /dashboard/licenses. Recopy it — check for leading/trailing spaces when you pasted it into the JSON.

The CEP panel doesn't show up in Photoshop

Symptom: You installed the .zxp but don't see "PS-MCP Bridge" under Window → Extensions.

Fix: Fully restart Photoshop after installing (closing and reopening the panel isn't enough). If it's still missing, confirm ZXP Installer finished without errors — an invalid signature fails silently on some Photoshop versions.

npx is slow on every launch

Symptom: Every time the MCP client starts, it takes 10-30s to load the server.

Fix: npx checks for an update on each launch. To make it instant, install it globally: npm i -g @synthetic-ai/photoshop-mcp then change command in the config to photoshop-mcp (no npx, no args).