Troubleshooting

Fix setup, sign-in, missing decisions, Rule, and approval problems.

Start with:

synkro --version
synkro whoami
synkro status

Use synkro status --json if you need detail. Fix the reported problem before retrying.

Report a problem to Synkro

Use Feedback to submit a bug or suggestion with available diagnostic context. Check the guide's command availability first. An approved agent connection can attach relevant evidence without asking you to assemble traces. If the command or sign-in is unavailable, keep a draft with the exact error and contact team@synkro.sh.

Command not found

brew list --versions synkro
brew --prefix
command -v synkro

Put Homebrew's binary directory on PATH, then open a new terminal.

For a direct Linux install, check ~/.local/bin is on PATH. See Install and verify.

Session service is unavailable

If the Synkro session service is unavailable, Synkro can block actions that need session or approval state.

Check synkro status and send the endpoint and error to team@synkro.sh.

Decision checks return 503

Run synkro status and synkro status --json. If decision admission is unavailable, Synkro cannot start the check. This is separate from a model failing to answer. A funded account can still show enforcement as active while service health is degraded.

Send the failure time, endpoint, error_code, and decision_id if provided, along with the status output, to team@synkro.sh. A successful check clears the service warning. For a hosted outage, wait for service recovery before retrying.

Homebrew fails on Linux

Homebrew may install its own compiler and system libraries on older Linux distributions. For locale or library errors during that installation, use the direct download below.

Use the direct Linux download instead. It needs no sudo or Homebrew. Check command -v synkro and synkro --version afterward so an older Homebrew copy does not take precedence.

Agent upgrade recovery

Upgrading a legacy agent registration to the current delegated connection protocol requires a one-time reconnection. This does not apply to an already working delegated connection when updating to rc.24. Legacy agent credentials and saved claim files cannot be resumed by the new protocol. Your human account, organization, card and balance are retained. Human CLI sign-ins do not need this cutover.

The current CLI identifies the saved file that cannot be read and the expected sign-in or setup format. It preserves the file and directs incompatible upgrades here. Older binaries may report unreadable / authentication.credentials_invalid or only authentication failed. These errors can occur locally, before a server request. Moving only credentials.json aside is insufficient because agent-claim.json is also incompatible.

For a confirmed legacy agent registration, have the human or Synkro support perform this explicit cutover. Stop onboarding commands and the agent session using that installation first. Do not apply it to a working delegated connection, a human sign-in, or an unrelated malformed file.

Run synkro whoami --json in the same installation environment. Use its credentialFile as the exact credential path. Locate that installation's configured agent_claim_file too: its default is agent-claim.json in the Synkro state directory. Honor SYNKRO_HOME, SYNKRO_DIR, SYNKRO_AUTH_FILE, SYNKRO_AGENT_CLAIM_FILE and settings-file overrides; do not guess another installation's paths.
Make a private backup of both files, then move those two originals out of their configured locations. If credentials were already moved aside, retain that backup and move the remaining claim file. Keep the backup private; it contains credentials and must never be pasted into chat or feedback. Preserve install_id, onboarding.json, settings, rules, hook configuration and queued observations. Do not delete the account, organization or entire Synkro directory.
Keeping the same installation and sandbox/production settings, run the released rc.24 binary:
```
synkro onboard claim --email YOUR_EXISTING_EMAIL --json
```
Use plain claim here: the old attempt has been retired, so there is no current link for --new-link to replace. This requests a connection to the existing account, not another signup.
Give the human the returned verification_url. They sign in to the existing account on Synkro's page and click Connect agent. Approval happens at this link after signing in; there is no separate approval email to wait for.
Run synkro onboard resume --wait-seconds 300 --json, then synkro whoami --json. Collection must report next.action = install and identity must report authenticated = true, the intended account and credentialKind = agent. Run synkro status and verify a governed action before treating enforcement as restored.

This recovery reconnects the existing account without an account reset. If a fresh claim fails after both incompatible files are backed up and retired, keep its newly saved state and report the error to Synkro support. Repeating the cutover will not repair an unrelated service failure.

Agent account claim did not finish

Use the newest email code and finish one connection at a time for that email. Keep browser storage enabled. The claim link disappearing from the address bar is expected: the page saves it in that tab.

Retry setup: your email was verified, but a service request failed. Retry in the same tab. Confirmed card details and starter credit are kept.
Verify email again: the saved sign-in is missing or can no longer be used. Follow that link and request a fresh code for the same account.
Missing or expired connection: ask your agent to run synkro onboard claim --new-link, then open and approve the new link. This keeps your existing account and organization.
Reconnecting after logout on the current protocol: run synkro onboard claim with the saved account. Approve the new agent connection, then run synkro onboard resume --wait-seconds 300. You do not need to submit another signup or remove saved files. For a legacy agent registration upgrade, use Agent upgrade recovery first.

An existing organization with confirmed starter credit does not need another card or receive another grant. A clean CLI installation does not make it a new organization.

The agent can run synkro onboard resume --wait-seconds 300 --json to collect the connection. Until it connects, claim_account and empty identity fields mean the CLI is not authenticated, not that no account exists. If retries keep failing, send the error, reference number if shown, and failure time to team@synkro.sh. Do not share email codes, credentials, or connection links.

Run one onboarding command at a time. If Synkro says another onboarding command is running, wait for that command to finish and read its result before retrying. Keep the saved setup and claim link. Older versions can report this conflict as authentication failed; update to 0.2.0-rc.24 before retrying.

Browser approval and CLI collection are separate steps. Wait for the terminal's final result: next.action = install means credentials were collected, whereas claim_account means approval is still pending. If the wait ends first, resume the same saved setup. The current CLI also retries temporary collection failures within --wait-seconds and checks for an already-approved result before replacing a link. Users on earlier versions should first try synkro onboard claim --json without --new-link when the browser already reported success.

whoami showing saved identity with an expired token is different from all identity fields being empty. The current CLI attempts renewal and provides recovery guidance; earlier versions only read the cached token. Neither output proves that browser account creation failed. Do not delete the account or saved setup to retry. If your terminal and agent disagree, compare their installId and credentialFile from whoami --json. Different installation roots or credential-file overrides can make them inspect different sign-ins.

With rc.24 and the matching service update, if a CLI process stops during collection, resume its saved setup. The service keeps bounded completion work running after the request disconnects and retains the encrypted result for collection. A confirmed expired/rejected attempt can return a renewed link for human approval; an unknown provider outcome instead asks for support. Keep the saved files in either case.

Signed-out hooks tell the agent that enforcement is paused and that work can continue. Fresh installations point to signup/sign-in; saved agent setup points to synkro onboard resume. This notice does not register an account or block a tool. Cursor can deliver the model-facing notice at session start or after a tool call; its pre-tool user message remains visible to the human.

Keep the terminal process running while you sign in. On the connection page, click Connect CLI and allow the browser to access this device if prompted. If access was denied, allow local network access in the browser's site settings and click Retry connection in the same tab.

If your browser is on another machine, or you prefer not to grant local access, cancel the waiting command and use:

synkro login --no-browser

Open the printed URL and enter the short code. An expired or denied code needs a fresh login attempt.

Run synkro whoami to confirm sign-in. If installation was interrupted, run synkro install again.

Browser approved, but the CLI failed

After browser approval, the CLI saves your sign-in. If that step fails, follow the terminal error below.

For Invalid last symbol 105, offset 9, upgrade to 0.2.0-rc.24 using Install and verify, then retry sign-in. This resolves a credential-format mismatch in older CLI versions and preserves your existing data.

For other failures, include synkro --version, your operating system, and the terminal error when asking for help. After the failure is resolved, run synkro login, confirm synkro whoami, then resume synkro install.

A rule package cannot be downloaded

Synkro's default cwe-baseline package is public. You should not need a separate repository account to download it. Check your network, proxy and Git configuration if it cannot be fetched. The package URL and exact revision are in ~/.synkro/synkro.toml.

After correcting access, retry:

synkro lock --path ~/.synkro
synkro install

Then run synkro lock inside your project. It validates all declared packages before replacing the lockfile. Contact support if the public package is still inaccessible.

Account commands return 403 or 404

synkro account and synkro account pay require an organization owner. A member receiving 403 from either command should ask an owner; members can read balance and usage. If those reads also fail, or a route returns 404, send the CLI version, endpoint and exact error to support.

Enforcement is paused

When enforcement is paused, agent actions continue with a notice but without Rule checks.

Check sign-in and network access. If the notice says funds are missing:

synkro account balance

An organization owner can use Billing and usage to add funds and check spending.

Follow the remedy in synkro status, then confirm enforcement is active.

Cannot reach the service

Check your network connection and the endpoint in synkro status --json. If your administrator supplied a different address, set it with synkro install --daemon-url URL and check status again.

If the service remains unavailable, send the endpoint and error to team@synkro.sh.

No new decision appears

synkro status --json
synkro events --limit 10 --json

Check that:

You asked the agent to run the action, rather than running it yourself.
You started a new session after installation.
The agent's Synkro integration is enabled and its hooks are trusted.
Enforcement is active.
You are reading the intended daemon, shown in endpoint.

In Codex, use Hooks settings or /hooks in the terminal interface. Check configuredMcp.codex and plugins.codex.toolBoundaryReady too.

For an unknown plugin status, check the setting in your agent's interface, then verify a decision.

If an error includes a trace ID, inspect it with synkro trace TRACE_ID, replacing TRACE_ID with that ID.

For provider.payload_invalid, update Synkro and its agent integration, then retry in a new agent session. The hook failed input validation, so the recorded result is error.occurred with a failed verdict stage rather than verdict.created. See Events.

Claude reports SessionEnd hook cancelled

Claude gives plugin shutdown hooks a separate budget, normally 1.5 seconds. That can expire before Synkro finishes recording session cleanup.

Update Synkro, run synkro update --yes, and start a new Claude session. Synkro adds CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS to the env object in ~/.claude/settings.json if the key is absent. It uses Synkro's configured hook budget, backs up the file, and removes only its unchanged addition on uninstall.

If you set this value yourself, Synkro leaves it alone. Check that it covers your hook timeout. A longer timeout gives cleanup time to finish; it does not repair an unreachable service. If cancellation continues, keep the trace ID and check synkro trace TRACE_ID.

The agent was installed after Synkro

Run synkro install again, then start a new agent session.

If installation reports one agent-specific error, fix that conflict instead of replacing the whole settings file.

A Rule does not take effect

Check the repository's synkro.toml. Installation alone does not add project Rules. Use synkro init only if there is no existing project file.

Then run:

synkro lock
synkro check --deterministic-only

Fix every reported error. Rule files belong directly under the declared package's rules/ directory.

Start a new agent session after locking so its hook uploads the project Rules. The next PreToolUse can also publish changes. Invalid changes leave the previous valid Rules active. For Git dependencies, run synkro lock update; agent actions do not fetch updates. Verify a new decision to confirm the published Rules were used.

Use synkro check for semantic examples too.

CLI and service versions differ

brew update
brew upgrade synkro-sh/tap/synkro
synkro update --yes
synkro status

Start a new agent session. Check command -v synkro if a development build still takes precedence over Homebrew's copy.

For a direct Linux install, repeat the rc.24 download before synkro update --yes. Report a service compatibility error to your administrator or team@synkro.sh.

Semantic checks are unavailable

Read the Semantic line in synkro status and health.components.semantic_judge in JSON. If a semantic check fails, an action can continue with an error notice. The error code and trace ID identify the failed check; send them to support.

Approval did not release the action

Use allow it for the latest pending request in the same session. The agent must retry the same action with unchanged inputs before approval expires, normally within 15 minutes.

A newer request may have replaced the old one. A block cannot be approved, and a fix still needs a corrected action. An unavailable session service cannot spend an approval.

A headless codex exec ends its session and cancels unresolved requests. codex exec resume ... "allow it" cannot recover that cancelled approval. Start an interactive Codex session, request the action again, then approve the new request in that live session.

See Consent for the approval steps.