Troubleshooting

Recoder is built to degrade truthfully — when something's missing, the relevant surface tells you instead of faking success. This page maps the common states to fixes.

“Backend not connected” everywhere

• •Give it a moment on first launch — the backend takes a few seconds to boot.
• •Make sure nothing else is bound to port 3100. You can override the port with the RECODER_BACKEND_PORT environment variable before launching.
• •If it persists, quit and relaunch so the supervisor respawns the backend.

An agent isn't detected

• •Confirm the CLI runs from a normal terminal (claude --version, codex --version, …).
• •Make sure it's on the same PATH Recoder inherited. If you installed it after launching Recoder, just refresh — detection is a live PATH probe.
• •If it's installed but shows unauthenticated, complete its own login / set its provider key, then refresh.

A merge won't land

• •Waiting on approval — check the Approvals view; a policy-gated merge pauses for a human decision.
• •Denied — the governance gate blocked it and shows a reason; address the reason rather than bypassing it.
• •Illegal transition — a workspace must be in a reviewable state before it can merge; finish review/converge first.

Converge marked a file as a conflict

When two agents edit the same lines incompatibly, synthesize won't invent a resolution — it flags the conflict and stops on that file. Resolve it by picking one agent's version of that file, or converge the rest and handle that file by hand.

An engine/feature says “not configured” or “unavailable”

Some optional engines (semantic code search, browser verification) depend on components that may not be present in every build or environment — for example provider keys or Python sidecars. When a dependency is missing, the engine reports not configured / unavailable on purpose, rather than pretending to work. The core parallel-run → converge → governed-merge loop does not depend on these optional engines.