Troubleshooting

Each entry title is the message or the state that you see.

Start with the Diagnostics panel. It checks the harnesses, Git, and the selected workspace.

Diagnostics

To open the panel, select the shield icon at the bottom of the sidebar, beside Settings.

DiagnosticsRefresh

Everything is working

3 runtimes are ready. The workspace checks passed.

Host

Shared by all workspaces

Agent runtimes

OpenCodeopencode v2.0.31

/Users/sam/.opencode/bin/opencode

ReadyRestart

Codexcodex-cli 0.163.0

/opt/homebrew/bin/codex

ReadyRestart

Claude2.1.316 (Claude Code)

/Users/sam/.local/bin/claude

ReadyRestart

Tools and services

PATH

Available

Git2.50.1 (Apple Git-155)

Executable/usr/bin/git

Available

OpenDucktor MCP bridge

Addresshttp://127.0.0.1:41287

Ready

Workspace

Selected workspace only

fieldnotes/Users/sam/code/fieldnotes

Repository setup

Worktrees/Users/sam/.openducktor/worktrees/fieldnotes

Configured

Task store

Database/Users/sam/.openducktor/task-stores/fieldnotes/database.sqlite

Ready

Refresh runs each check again, and each row shows its result.

Check	What it needs
Agent runtimes	Each enabled harness is installed and Ready.
PATH	The host can read your user PATH to find Git and the harnesses.
Git	Git 2.41 or later.
OpenDucktor MCP bridge	The bridge that agent sessions and MCP clients use to reach the host is Ready.
Repository setup	The selected workspace has a worktree path.
Task store	The task store of the selected workspace is Ready.

Installation

The install scripts print each error after OpenDucktor install:. When an install fails, they keep or restore the previous app. A fix works when the script ends without an error.

The Agent runtimes card in Diagnostics shows the state of OpenCode, Codex, and Claude Code. Host messages name the settings section Settings > Runtimes. In the Settings dialog, its name is Agent runtimes.

Workspaces

The Workspace group in Diagnostics checks the selected workspace only.

Git providers

These problems show in the Git tab of a repository in Settings, or in the Git provider step of the setup wizard.

External MCP

The @openducktor/mcp server writes its startup errors after [openducktor-mcp]. Most MCP clients show them in their server log. After each fix, check that your MCP client lists the odt_* tools.

Browser runner

These problems stop the browser runner, npx @openducktor/web, or block its web page.

Remote control

These problems affect the host when you share it, and the computers and browsers that connect to it. For the mobile app, see Mobile.

Mobile

To see the checks of the connected host, open the Host tab in the app, then Diagnostics.

Logs

The desktop app and the browser runner write one log file each day and delete files older than 30 days. To open the log folder, run:

open ~/.openducktor/logs

Program	Log file
Desktop app	`openducktor-electron-YYYY-MM-DD.log`
Browser runner	`openducktor-web-YYYY-MM-DD.log`

If you set OPENDUCKTOR_CONFIG_DIR, the logs are in its logs folder. The MCP server and the mobile app write no log file. For a mobile problem, collect the log of the host.

Copy the log lines from before, during, and after the problem. Remove repository names, paths, and other text that you do not want to make public.

Report a problem

Search the open GitHub Issues for the same problem.
Select New issue, then Bug report.
Give the steps to reproduce the problem, the result that you expected, and the result that you got.
Add these details:
- The OpenDucktor version from Settings, General.
- Your operating system, and how you run OpenDucktor.
- For a session problem, the harness version from Diagnostics.
- The exact error message and the Diagnostics overview.
- The log lines.

Security problems

Report a security problem as the security policy describes. Do not put it in a public issue.

Troubleshooting

Diagnostics

Installation

Harnesses

Workspaces

Git providers

External MCP

Browser runner

Remote control

Mobile

Logs

Report a problem

Next

Install and update

Harnesses

Settings reference

On this page

Troubleshooting

DiagnosticsCopy Anchor Link

A check shows Timed out or Check unavailableCopy Link

PATH shows IssueCopy Link

Git shows IssueCopy Link

InstallationCopy Anchor Link

Homebrew manages OpenDucktor.Copy Link

Another installer or another copy of the app existsCopy Link

Unsupported systemCopy Link

The downloaded asset SHA-256 differs from the GitHub release digest.Copy Link

The macOS app signature failed verification, or macOS did not accept the app signature.Copy Link

Windows protected your PCCopy Link

The update prompt shows Manual update requiredCopy Link

The update prompt shows Install needs attentionCopy Link

HarnessesCopy Anchor Link

Cannot start the OpenCode, Codex, or Claude runtimeCopy Link

A harness shows Needs attention in SettingsCopy Link

Goals need OpenCode 2.2.1 or laterCopy Link

OpenCode has no /goal commandCopy Link

Set a default model in the repository settings to generate a goal.Copy Link

The OpenCode, Codex, or Claude runtime stopped unexpectedlyCopy Link

A harness shows Retry applyCopy Link

The row shows an unexpected version or an In use pathCopy Link

WorkspacesCopy Anchor Link

Task store shows Blocked or Degraded, or New task shows Task store unavailableCopy Link

Workspace is not a Git repository, or Not a git repositoryCopy Link

The sidebar shows Tasks could not loadCopy Link

A workspace is missing from the sidebarCopy Link

Before worktree removal script command failed:Copy Link

Git providersCopy Anchor Link

Install GitHub CLI (gh) to enable provider-backed pull requests.Copy Link

GitHub authentication is not configured. Run gh auth login.Copy Link

GitLab rejected the token, or the token lacks the api scopeCopy Link

No local Git remote points to the GitLab projectCopy Link

No local Git remote maps to the configured Azure DevOps repository.Copy Link

The operating system does not trust the TLS certificateCopy Link

The operating system secure credential store is unavailable.Copy Link

External MCPCopy Anchor Link

No running OpenDucktor host was discovered.Copy Link

No healthy OpenDucktor host was discovered.Copy Link

The OpenDucktor MCP bridge row in Diagnostics shows ErrorCopy Link

Configured default workspace '<id>' was not found on the running OpenDucktor host.Copy Link

Missing workspaceId for workspace-scoped toolCopy Link

A tool result says Workspace is not configuredCopy Link

The OpenDucktor host bridge is incompatible, or is missing required MCP toolsCopy Link

Invalid, failed parsing, or failed reading of the OpenDucktor MCP discovery fileCopy Link

The client cannot start the server, or bun is not foundCopy Link

Browser runnerCopy Anchor Link

npx @openducktor/web stops at startupCopy Link

The browser runner stops because a port is in useCopy Link

OpenDucktor web binds a non-loopback host without a remote --external-url.Copy Link

Network browser pages require HTTPS.Copy Link

OpenDucktor web serves the TypeScript host under --base-path without --external-url.Copy Link

A browser on another computer gets a 403 response, such as Host not allowed.Copy Link

Remote controlCopy Anchor Link

This web app needs an HTTPS host address.Copy Link

This browser blocked access to your local network.Copy Link

Remote control says that the port is in use by another appCopy Link

Remote control says that the address is not on this computer nowCopy Link

The pairing code is wrong, expired, or already used.Copy Link

No pairing code is open on the host.Copy Link

This device needs a new pairing code.Copy Link

This host does not support secure pairing.Copy Link

A client cannot read a host result, or asks you to updateCopy Link

MobileCopy Anchor Link

Can't reach your host, or Can't reach the hostCopy Link

Reconnecting shows for a long timeCopy Link

OpenDucktor needs Local Network access to reach this host.Copy Link

Saved access is missing on this device.Copy Link

The QR code scan does not startCopy Link

This device does not trust the host certificate.Copy Link

LogsCopy Anchor Link

Report a problemCopy Anchor Link

NextCopy Anchor Link

Install and update

Harnesses

Settings reference

On this page

Diagnostics

Installation

Harnesses

Workspaces

Git providers

External MCP

Browser runner

Remote control

Mobile

Logs

Report a problem

Next