Troubleshooting

Troubleshooting

First step for any problem: in the panel, ☰ › Test the connection (or 2. Test Installation from the zip, or node ~/.surehand/ae/server/surehand-ae.mjs selftest). Every failed line says what's wrong and how to fix it.

Symptom → fix

What you see	What to do
Surehand MCP is not in Window › Extensions	See The panel is missing.
"Cannot reach After Effects"	Make sure After Effects is running and has finished starting. Open Window › Extensions › Surehand MCP to see the bridge status. If you just installed, restart After Effects. If the panel is missing, see below.
"After Effects is busy or showing a dialog"	See After Effects is busy.
A call times out	After Effects can't interrupt a running script: a long script, a render or a dialog keeps it busy. Check After Effects, then retry. For long jobs the AI can pass timeoutSeconds.
The panel says Bridge not running or Bridge problem: …	Restart After Effects. If it says "Ports 8765-8774 are all in use", other programs hold those ports: close them, or set bridgePort in config.json and restart After Effects and your AI app.
"After Effects is still running the previous Surehand panel (v…). Restart After Effects to finish the update."	You updated while After Effects was open. Restart After Effects; nothing else is needed. The panel shows Restart After Effects to finish the update until then.
"After Effects didn't undo anything: a dialog may be open in After Effects"	A dialog or warning is open in After Effects (some start-up warnings appear at every launch), and Edit › Undo does nothing while it is. Close it, then ask again. See A dialog is open in After Effects.
The self-test fails "Edit > Undo" and skips the undo checks	The same: close the dialog in After Effects and run the self-test again.
The panel says Token mismatch: re-run the installer	Re-run the installer (it keeps the existing token), then restart After Effects.
The panel says Settings file can't be read: …	~/.surehand/ae/config.json has a mistake in it. Fix it (it's JSON), or re-run the installer. Until then, changes to the project are refused.
The AI app doesn't see the tools	See The AI app doesn't see Surehand.
Claude Desktop doesn't show the tools	See Claude Desktop doesn't show the tools.
"Paused in the Surehand panel: nothing was run"	You (or someone at this computer) paused the AI. Click Resume in the panel. With several After Effects open, resume in each one that shows AI paused.
"The user denied this change in After Effects"	Someone clicked Deny (or pressed Esc). Nothing ran.
"No one approved this change … within 10 minutes"	Ask mode is on and nobody answered. Nothing ran. Switch to Full, or answer the requests.
"Surehand MCP is in read-only mode"	The panel is set to Read-only. Switch What the AI may do to Full or Ask.
"Shell commands (system.callSystem) are disabled"	☰ › Shell commands in scripts › Allowed, if you want to allow them.
Scripts can't write files or use the network	In After Effects: Settings › Scripting & Expressions › Allow Scripts to Write Files and Access Network. Surehand's own tools and previews work without it.
Preflight: "ffmpeg isn't installed, so the file checks didn't run"	Let the AI download it once (it asks you), or install it yourself: brew install ffmpeg (Mac), winget install ffmpeg (Windows). Or set ffmpegPath in config.json. In Read-only mode it never downloads. See Preflight.
Preflight says INCOMPLETE	A check you asked for couldn't run. The report lists which and why (no ffmpeg, an RGB file for legal range, an older After Effects for text overflow or glyphs).
ChatGPT (web): "ChatGPT needs a free tunnel tool, cloudflared"	Install cloudflared. See ChatGPT on the web.
A ☰ screen says "This needs the Surehand MCP app installed with its installer"	You installed only the Claude Desktop extension (.mcpb). Install with the .pkg, Setup .exe or zip to use these screens.
A ☰ screen says "This needs a newer Surehand MCP server"	Update: ☰ › Check for updates…, or re-run the newer installer.
Chat: No AI app ready or Not signed in	See Chat in After Effects.
Windows: "Windows protected your PC"	See Windows SmartScreen.
Mac: "cannot be opened because it is from an unidentified developer"	See macOS blocks the files.
Undo in the panel says "The project changed since then"	Something changed the project after the AI's step. Use Edit › Undo in After Effects, step by step.

The panel is missing from Window › Extensions

1. Restart After Effects fully. After Effects only loads new or updated extensions when it starts.
2. Run the self-test (2. Test Installation, or selftest). It checks the extension's files against their signature. After Effects silently skips a signed extension whose files changed (for example after an antivirus or sync tool touched them).
3. Re-run the installer. It rewrites the extension files.
4. Last resort: allow unsigned extensions. This makes After Effects load the extension even if its signature doesn't match. It affects all CEP extensions, so use it only if the steps above didn't help.
   • macOS: defaults write com.adobe.CSXS.12 PlayerDebugMode 1 (and the same for the CSXS version your After Effects uses), then restart After Effects.
   • Windows: in the registry, HKEY_CURRENT_USER\Software\Adobe\CSXS.12, add a string value PlayerDebugMode = 1, then restart After Effects.

The bridge also starts without the panel: if the panel opens but says the bridge isn't running, the panel starts the bridge itself after a few seconds.

After Effects is busy or showing a dialog

"After Effects is busy or showing a dialog: it has not accepted a script for 3s."

A dialog or settings window is open in After Effects (Project Settings, Preferences, an alert, a render in progress), or After Effects is still starting.

• Close the dialog and ask the AI to retry. The call did not run and won't run later.
• Scripts that have already started are never cut short.
• Reported after 3 seconds. Change it with "blockedAfterSeconds" in config.json (0 waits for the full timeout).

ae_status shows what After Effects is busy with and for how long.

A dialog is open in After Effects

Some dialogs don't stop scripts from running but stop Edit › Undo: for example a warning After Effects shows at every launch (such as one about the disk cache folder). While one is open, undo does nothing. Surehand checks this instead of assuming it worked:

• ae_undo and ae_redo check that After Effects really undid each step. If nothing was undone, they say "After Effects didn't undo anything: a dialog may be open in After Effects (close it and try again), or there is nothing left to undo." If only some steps were undone, the result says how many.
• The full self-test probes undo first. If it doesn't work, it reports one clear failure ("Edit > Undo: … close the dialog and run the self-test again") and skips the checks that need undo.

Bring After Effects to the front, close the dialog, and retry.

The AI app doesn't see Surehand

1. Restart the AI app after installing. Most apps only read their MCP settings when they start.
2. In the panel: ☰ › Connect an AI app…. If the app says Not connected, click Set up, then restart the app.
3. If the row has a note, it says what's wrong, for example "its Node.js no longer exists" or "the server it runs no longer exists" (Set up fixes it), or "its settings file can't be read" (fix that file first: Surehand doesn't touch it until then).
4. ChatGPT desktop / Codex: check Settings › Plugins › Servers and switch surehand-ae on.
5. Ask the AI app: "Call ae_status." If it says the tool doesn't exist, the app hasn't loaded the server.

Claude Desktop doesn't show the tools

A Claude Desktop that is running while its settings file changes can write its old settings back when it quits. The surehand-ae entry is then lost.

1. Quit Claude Desktop completely: Cmd+Q on a Mac, tray icon › Quit on Windows.
2. In the panel: ☰ › Connect an AI app…. If Claude Desktop shows Not connected, click Set up. (Or re-run the installer.)
3. Open Claude Desktop.
4. Check: claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\) contains surehand-ae under mcpServers.

If you use the .mcpb, check Settings › Extensions in Claude Desktop instead. Don't use both the .mcpb and an installer entry.

The AI is talking to the wrong After Effects

With several After Effects versions open, the AI uses the one you used most recently. Ask it to switch: "Use After Effects 2025." (ae_status with instance: "2025"). For a permanent preference, set "instance": "2026" in config.json.

Windows SmartScreen

"Windows protected your PC" when you open a launcher or Setup:

1. Click More info.
2. Click Run anyway.

The 1.4 Setup .exe is signed; SmartScreen can still warn about a new release until it has built up reputation. The .bat launchers in the zip aren't signed.

macOS blocks the files

"… cannot be opened because it is from an unidentified developer" (or "Apple could not verify…") when you double-click a launcher from the zip:

1. Open System Settings › Privacy & Security.
2. Scroll down and click Open Anyway next to the blocked file.
3. Double-click the file again. This is needed only the first time.

The 1.4 .pkg is notarized by Apple and doesn't need this.

Reporting a problem

1. Run ☰ › Test the connection or 2. Test Installation. If anything fails, it prints a diagnostics report (no secrets in it).
2. Or click ☰ › Copy diagnostics in the panel, or run surehand-ae diagnostics.
3. Open an issue at github.com/ConformLabs/surehand-mcp/issues with the report, your After Effects version and what you asked the AI to do.

On Windows, %USERPROFILE%\.surehand\ae\bridge-status.json also helps.