Troubleshooting issues

Use this page when Conductor cannot start work, run a project, restore a workspace, or merge a finished branch.

Authentication issues

Use this section when Conductor cannot create workspaces, start agents, fetch GitHub data, or call a model provider.

GitHub

Conductor expects GitHub authentication to work in your terminal environment.

Run:

gh auth status

If the command fails, sign in again:

gh auth login

Then restart Conductor and try the action again.

Claude Code

If Claude Code cannot start or authenticate, run:

claude /login

Conductor uses the Claude Code authentication available on your machine unless you configure provider-specific environment variables.

Codex

If Codex cannot start, check the model picker and your OpenAI authentication or subscription setup. If you configured an API key, confirm it is available in Conductor's environment settings.

Custom providers

If a custom provider fails:

1. Confirm the provider environment variables are set in Settings -> Env or Repository Settings.
2. Confirm the provider supports the model you selected.
3. Restart the affected chat after changing provider variables.

For provider examples, see Configure model providers.

Script issues

Use this section when setup scripts, run scripts, or archive scripts fail.

Setup script fails

The setup script runs inside the newly created workspace. It should only depend on files that exist in the workspace or paths exposed through Conductor environment variables.

Check these common causes:

• The script expects ignored files such as .env to be copied automatically.
• Dependencies are installed in the repository root but not in the workspace.
• The script assumes a fixed absolute path.
• A command needs authentication that is not available in the workspace shell.

Use $CONDUCTOR_ROOT_PATH when the script needs to read from the repository root.

Run script fails

The run script runs when you click the Run button.

Check these common causes:

• The app uses a fixed port that is already in use.
• Multiple workspaces are trying to use the same database, cache, or external service.
• The script starts a background process with & instead of running the foreground process.
• The command works in your root checkout but not in a workspace.

Use $CONDUCTOR_PORT for workspace-specific ports.

Archive script fails

The archive script runs before Conductor archives a workspace. Keep it focused on cleanup for resources outside the workspace directory.

If the script fails, archive may not complete. Fix the command and try again.

Environment variables are missing

Conductor exposes variables such as CONDUCTOR_WORKSPACE_PATH, CONDUCTOR_ROOT_PATH, and CONDUCTOR_PORT to terminals and scripts.

For the full list, see Conductor environment variables.

Agent issues

Use this section when a chat is not progressing as expected.

The agent is waiting for input

If the sidebar shows that a session needs input, open the workspace and answer the agent's question. The agent may be blocked on a product decision, missing context, or a requested approval.

The agent needs permission

Review the requested action before approving it. If the action is not needed, deny it or ask the agent to use a different approach.

Permission prompts can appear for shell commands, tool use, MCP access, web access, or file changes.

The agent is in the wrong mode

If the agent keeps planning instead of editing, exit Plan Mode. If it starts editing before you want it to, enter Plan Mode and ask for a plan first.

For mode details, see Agent modes.

The agent appears stuck

Try these steps:

1. Wait for any running command to finish.
2. Check whether the agent is waiting for approval or user input.
3. Cancel the current response if it is no longer useful.
4. Start a new message with the exact next action you want.
5. If the chat state is confused, start a new chat or use a checkpoint if available.

Use Checkpoints when you need to revert both code changes and later chat state.

Workspace issues

Use this section when a workspace cannot open, cannot be restored, or conflicts with another workspace.

Restore an archived workspace

Open the Workspaces page from the sidebar. Find the workspace and restore it. Conductor restores the chat history and workspace state it has saved.

A workspace path is missing

If a workspace directory was moved or deleted outside Conductor, Conductor may not be able to open it.

Use the Workspaces page to inspect the workspace. If restore fails, create a new workspace from the branch or pull request and continue from there.

A branch is already checked out

A Git branch can only be checked out in one worktree at a time. If Conductor cannot create or switch to a branch, another workspace or local checkout may already be using it.

Use one of these fixes:

• Switch the other workspace to a different branch.
• Create a new branch based on the existing one.
• Archive the old workspace if you no longer need it.

Old nested .conductor workspaces

Older Conductor repositories may still have workspaces inside a .conductor folder under the repository root. Newer workspaces live under ~/conductor/workspaces/.

If nested source directories confuse your build tools, remove and re-add the repository:

1. Find the workspace name in the sidebar.
2. Next to the name, click the "Repository details" button.
3. Click "Remove". This deletes all workspaces and chats for that repository.
4. Add the repository again.

If you still run into issues, contact support@conductor.build.

Review and merge issues

Use this section when a workspace is close to merge but Conductor still shows blockers.

Checks are failing

Open the Checks tab and inspect the failing item. If the failure includes logs or enough context, send it to the agent and ask for a fix.

Run the relevant test locally before trying to merge again.

Comments are unresolved

GitHub review comments and local review comments may appear in the Diff Viewer or Checks tab.

For each comment:

1. Send it to the agent or fix it yourself.
2. Confirm the diff changed as expected.
3. Resolve the thread when the issue no longer applies.

Todos are blocking merge

Open the todos section and complete or remove each todo. Conductor blocks unfinished work so a workspace does not merge while known tasks are still open.

Merge conflicts

Pull the latest changes from the target branch, inspect conflicts, and ask the agent to resolve them if needed. Give the agent the conflict context and the intended behavior, not only the command output.

After conflicts are resolved, rerun tests and review the diff before merging.

Known issues

Why doesn't undo (cmd+z) work when I'm writing a message?

The library we use to do @-mentions breaks the undo history. We're looking into other solutions.

Why do I see garbage when I switch between terminal windows?

We're streaming output from your shell along to the UI, and at some point along the way, the stream is probably getting corrupted. We're still working to track down this bug.