# Troubleshooting > Fix setup, sign-in, missing decisions, Rule, and approval problems. Source: https://docs.synkro.sh/troubleshooting Start with: ```sh 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](/guides/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](mailto:team@synkro.sh). ## Command not found ```sh 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](/onboarding/install). ## 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](mailto: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](mailto: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](/onboarding/install#linux-without-homebrew) 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. 1. 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. 2. 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. 3. Keeping the same installation and sandbox/production settings, run the released rc.24 binary: ```sh 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. 4. 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. 5. 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](#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](mailto: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. ## Browser sign-in did not finish 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: ```sh 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](/onboarding/install#update-an-existing-installation), 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: ```sh 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: ```sh synkro account balance ``` An organization owner can use [Billing and usage](/guides/billing) 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](mailto:team@synkro.sh). ## No new decision appears ```sh 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](/onboarding/verify-events). 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](/guides/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: ```sh 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 ```sh 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](/onboarding/install#linux-without-homebrew) before `synkro update --yes`. Report a service compatibility error to your administrator or [team@synkro.sh](mailto: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](/guides/consent) for the approval steps.