Troubleshooting

Start from the symptom, not the subsystem. Each entry gives the most likely cause, the fix, and the page that explains the machinery.

The install is blocked by SmartScreen or Gatekeeper

Symptom: Windows shows “Windows protected your PC”; macOS says the app “cannot be opened because the developer cannot be verified”.

Likely cause: Birch builds are currently unsigned and not notarized, so both operating systems flag the first launch. This is expected; code signing is planned.

Fix:

• Windows: in the SmartScreen dialog, click More info → Run anyway.

• macOS: in Finder, right-click Birch.app → Open → Open. Or remove the quarantine attribute in a terminal:

  terminal

  xattr -dr com.apple.quarantine /Applications/Birch.app

Full install steps, including system requirements: Installation.

The agent status disc never updates

Symptom: a workspace’s status indicator never shows working / waiting / done while the agent is clearly busy, and agent activity never reaches the Inbox.

Likely cause: status is push-based — Claude Code hook events reach Birch through the birch-status plugin, which runs the birch CLI. The chain breaks when:

1. the birch-status plugin isn’t installed in Claude Code, or
2. the birch CLI isn’t on your PATH, so the plugin’s hooks have nothing to run, or
3. a different (older) birch binary shadows the bundled one — Settings → Claude Code reports this as “A different birch is first on your PATH”.

Fix: open Settings (⌘, / Ctrl+,) → Claude Code and use Install plugin and Install birch CLI to PATH. Then open a new terminal and confirm birch --help works. You can also install the plugin from inside Claude Code:

text

/plugin marketplace add https://github.com/aidmsu/birch-code
/plugin install birch-status@birch

If the plugin is installed but outdated, use the pane’s Update button — plugin installs are frozen snapshots and don’t update themselves.

How the pipeline works end to end: The birch-status plugin.

✨ buttons are missing or error out

Symptom: the ✨ button next to the commit message is not there, or an AI action fails with “AI provider is not configured. Set ANTHROPIC_API_KEY.”

Likely cause: the Anthropic API features — commit-message generation, AI code review, conflict suggestions, comment-fix suggestions — read the ANTHROPIC_API_KEY environment variable; there is no key field in Settings. A GUI app launched from the Dock or Start menu does not inherit exports from your shell profile, so a key that works in your terminal can be invisible to Birch.

Fix: make the variable visible to GUI apps and restart Birch — platform-specific steps are in Anthropic API key.

Note

The ✨ button beside the PR Title is different: it runs your own agent CLI (claude or codex) and does not need the API key. If that one fails, the agent CLI itself is missing or not found on your PATH.

A new workspace is missing my .env

Symptom: a freshly created workspace doesn’t contain the .env (or similar local config) that exists in your main checkout.

Likely cause: Birch carries over files that are git-ignored and match a carryover pattern (the built-in default is .env*). Two common ways this breaks:

• the file is not git-ignored — tracked files are checked out by git anyway, but an untracked-and-not-ignored file is deliberately never copied;
• a .worktreeinclude file at the repository root replaces the default patterns wholesale — an empty or unreadable file means nothing is carried.

Fix: git-ignore the file, and either rely on the default .env* or list it in .worktreeinclude. Carryover runs only when the worktree is created, so re-create the workspace (or copy the file by hand) after fixing the patterns. Details: .worktreeinclude.

Provider sync or auth failures

Symptom: PRs or tasks stop updating for one account, or connecting an account fails.

Likely cause: an expired or revoked token, an under-scoped token (for example a GitLab token without api, or a Jira Cloud token made with scopes), or a wrong self-hosted base URL (Jira / Azure DevOps / YouTrack / GitHub Enterprise). Verify & connect only checks whose token it is, so an under-scoped token connects fine and fails later.

Fix: open Settings → Integrations and check the account card — it shows the last Verified timestamp. Try Sync now; if that fails, Remove the account and reconnect with a fresh token, granting everything the connect form’s Token permissions list names. Verify & connect validates the credential before anything is saved, so a failed connect never clobbers a working account. A refused PR merge, close, draft or review names the permission to check in its error. Per-provider token permissions and URL formats: Token permissions and the individual provider pages.

The CLI can’t reach the app

Symptom: a birch command doesn’t affect the running app, or birch open fails.

Likely cause: the CLI talks to a running Birch app over a named pipe. If no app is listening, behavior depends on the command:

• worktree new, worktree rm, pr checkout, review run — try the pipe first, then fall back to executing locally; the result appears in the app the next time it runs.
• open — launches Birch if it isn’t running and waits up to 15 seconds for the pipe; exit code 1 means the launch failed or the app didn’t accept.
• worktree ls, pr create, pr merge, pr list, status — always run locally and never need the app.

Fix: run the command with --verbose — it prints the routing decision to stderr (GUI detected — relayed via IPC or GUI not running — executing locally), which tells you immediately whether the pipe was reachable. Command reference: CLI overview.

The app launches but no window appears

Symptom: the Birch process starts but no window ever shows, and the log ends without an error.

Likely cause: a rare startup condition — most often a stale database migration lock left behind when a previous Birch process was killed mid-startup.

Fix:

1. Quit Birch completely (⌘Q / close it from the taskbar) and make sure no Birch process is still running.
2. Relaunch. Birch detects and reclaims a stale migration lock at startup, so a clean relaunch normally recovers on its own.
3. If the window still doesn’t appear, send a report from a terminal (If Birch won’t start) — don’t attempt to edit the database by hand.

Report a problem

Send a report from Birch instead of attaching log files by hand. Birch adds its own logs and error details, replaces or removes anything that could identify you, your projects, servers or accounts, and shows you everything before it’s sent.

1. Click Report a problem at the bottom of the sidebar, or Report a problem… in Settings → General → About & diagnostics.
2. Describe what you were doing and what happened instead. Your description is sent exactly as you typed it, so don’t paste passwords, tokens or code. If it mentions a folder path or an email address, Replace with placeholders swaps them out.
3. Check What will be sent. Each item shows its size, Preview shows exactly what will be uploaded, and you can untick anything except your description and the app details.
4. Click Send report. Birch shows a Report ID such as BR-7F3A-92CD — copy it, and mention it if you follow up.

Nothing is sent until you click Send report. Offline, or would rather send it yourself? Save report… writes the same file to disk. What a report contains and what happens to it: Privacy.

After a crash

The next time you open Birch after it closed unexpectedly — or didn’t quit normally, say after a force quit — it asks whether you’d like to send a report. Review report… opens the same dialog with the crash details included; Not now skips it. To stop the question, untick Offer to send a report after Birch closes unexpectedly in Settings → General → About & diagnostics.

If Birch won’t start

If Birch shows an error window instead of starting, click Report this problem… in that window. Its logs item starts unticked here: without its database, Birch cleans the logs by stricter rules, so preview them before you tick them.

If no window appears at all, send the report from a terminal. On macOS (adjust the path if Birch isn’t in Applications):

terminal

'/Applications/Birch.app/Contents/Helpers/birch' report --send

On Windows, the CLI is cli\birch.exe inside the current folder of the install folder — %LOCALAPPDATA%\Birch\current\ for a normal install. In PowerShell:

powershell

& "$env:LOCALAPPDATA\Birch\current\cli\birch.exe" report --send

If you installed the CLI to your PATH, birch report --send is enough. The command lists what the report contains and asks before sending anything; without --send it only prepares the report and shows you what’s in it, and the folder it’s in. Add --message "what went wrong" to describe the problem. Birch’s logs are left out unless you add --logs (and --older-logs for 4–7 days ago) — look at them in that folder first. All options: birch report.

Look at the logs yourself

Prefer to look first? Settings → Advanced → Open logs folder opens the folder where Birch writes daily rolling log files — birch-<date>.log for the app and birch-cli-<date>.log for the CLI. The most recent 14 days are kept:

Platform	Log folder
macOS	~/Library/Application Support/birch/logs/
Windows	%APPDATA%\birch\logs\

These are raw logs: unlike a report, they contain folder paths, repository and branch names, and server addresses. Read one before you share it, and never attach one to a public issue. The full layout of the data directory is in Storage & data.