> ## Documentation Index > Fetch the complete documentation index at: https://docs.kentron.ai/llms.txt > Use this file to discover all available pages before exploring further. # Troubleshooting the CLI > Find the exact message the receipt binary printed, learn what caused it, and run the one command that fixes it. Almost every failure in the released `receipt` binary is a fixed sentence, so the fastest route to a fix is to search this page for the message you got. Two commands resolve most of them: [`receipt doctor`](/cli/doctor), which reports without changing anything, and [`receipt setup`](/cli/setup), which signs you in again. ## Start with doctor `receipt doctor` resolves which host you are pointed at, probes the gateway and the sign-in origin, and prints the saved session with its expiry. It never opens a browser and never signs you in, so it is safe to run at any point. ```bash theme={null} receipt doctor receipt doctor --target local receipt doctor --json ``` It exits `0` when the gateway answers a health check with a 2xx, the sign-in origin answers at all, and any saved session is live and matches the gateway; it exits `1` otherwise. Three causes account for most of what it flags: * **You are not signed in**, or the session file was removed. * **The token expired.** CLI tokens last 12 hours and there is no refresh. * **You are pointed at the wrong host** — usually a `local` or self-hosted target whose stack is not running, or a session saved for a different target. ## Install and first launch | Message | Cause | Fix | | ------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | | `Missing required command: ` | The installer needs `curl`, `tar` and `awk`, plus `shasum` or `sha256sum` | Install the named tool and re-run the installer | | `Unsupported OS: ` | Only macOS and Linux builds are published | There is no Windows build | | `Unsupported architecture: ` | Only `arm64` and `x64` are published | Use an arm64 or x64 machine | | `Download failed: `, then `Check that this release and asset exist.` | A version or repository override points at a tag that does not exist, or the machine is offline | Unset `RECEIPT_CLI_VERSION` and `RECEIPT_CLI_REPO`, or name a tag that is actually published | | `checksums.txt has no entry for ` | The downloaded checksum file does not cover the asset | Re-run the installer; never install by unpacking the tarball by hand | | A `shasum` or `sha256sum` verification failure | The download was corrupted or does not match the release | Re-run the installer | | Your shell reports `command not found` for `receipt` | The install directory is not on `PATH` | Add the line the installer printed to your shell profile. If a different `receipt` answers, `command -v receipt` shows which one wins | | Exit code `137` on macOS, with no output | The binary carries the `com.apple.quarantine` attribute a browser download attaches, and macOS kills it at launch | `xattr -d com.apple.quarantine ~/.local/bin/receipt`, or reinstall with the `curl` installer, which does not set the attribute | **The macOS binaries are ad-hoc signed only** — `codesign -dv` on the published `receipt-darwin-arm64` reports `Signature=adhoc` and `TeamIdentifier=not set`, with no notarization. The signature itself is valid, so an installed binary runs; what macOS refuses is a copy that also carries the `com.apple.quarantine` attribute a browser download attaches. Such a copy exits `137` at launch and prints nothing, and your shell may report it as `Killed: 9`. Install with the published `curl … | bash` installer, which does not set the attribute, or clear it with `xattr -d com.apple.quarantine `. One rarer cause produces the same `137`: a published build whose own ad-hoc signature is malformed, which the release script smoke-tests for. If a freshly installed, unquarantined copy still dies at launch, the build is at fault and a newer release is the fix. Re-running the installer overwrites the binary at the same path and leaves `~/.receipt` alone, so your saved session survives an upgrade. `receipt mcp install codex` records an absolute path to the binary in the Codex config, so that entry survives an in-place upgrade too. If you move the binary instead — a different `RECEIPT_CLI_BIN_DIR`, or a manual install — Codex keeps calling the old path; run `receipt mcp remove codex`, then `receipt mcp install codex`, to repoint it. See [Install the CLI](/cli/install). ## Endpoint and target | Message | Cause | Fix | | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | | `receipt connect target must be prod, dev, local, or an http(s) URL` | A `--target` word that is not `prod`, `dev`, `local` or a full URL — including `receipt login ` | Use a target name or a complete `http(s)` URL | | `receipt connect production URL is not configured yet. Set RECEIPT_CONNECT_PUBLIC_GATEWAY_URL=https://app.kentron.ai and re-run, or set RECEIPT_CONNECT_PROD_GATEWAY_URL, RECEIPT_CONNECT_PROD_URL, or RECEIPT_CONNECT_URL.` | You are running a build with no hosted default baked in — a source checkout, or a release older than `v0.1.0-preview.7` | Upgrade to the current release, export one of the named variables, or pass `--server-url` | | `receipt connect dev URL is not configured. Set RECEIPT_CONNECT_DEV_GATEWAY_URL or RECEIPT_CONNECT_DEV_URL.` | `--target dev` has no built-in default | Export one of those two variables | | `Receipt gateway did not answer a health check (). Check RECEIPT_CONNECT_PUBLIC_GATEWAY_URL or --server-url.` | Wrong host, a stack that is not running, or a port mismatch on `local` | Correct `--server-url` or `RECEIPT_CONNECT_LOCAL_SERVER_URL`, and confirm the stack is up | | `Receipt sign-in origin is unreachable (). Check --auth-url.` | The sign-in origin is wrong or unreachable | It must be the exact origin your browser uses; set `--auth-url` or `RECEIPT_CONNECT_LOCAL_AUTH_URL` | | `Saved session targets , not ; run 'receipt setup' for this target.` | `doctor` was asked about one target while the saved session belongs to another | Run `doctor` with the target you signed in with, or `receipt setup --target ` | An unrecognised `--target` word is rejected **before** `--server-url` is applied, so `--target staging-two --server-url https://` fails on the target word even though you supplied an explicit URL. Pass the URL as the target instead. ## Signing in | Message | Cause | Fix | | -------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- | | `receipt connect device login failed to start: http_404` | The sign-in origin is not the web application — for example a gateway that does not serve the CLI login route | Pass `--auth-url ` | | `receipt connect device login failed to start: rate_limited` | An eleventh sign-in start within 60 seconds, or a fourth while three are still pending, from one client IP | Wait 60 seconds and retry | | `receipt connect device login failed to start: receipt_connect_storage_unavailable` | The sign-in endpoint threw on the server and answered `503`; the usual reason is that the store for pending logins is unreachable | Retry later; this is an operator problem | | `receipt connect device login request failed for : ` | A network failure or a timeout on the start request | Check connectivity to the sign-in origin, then retry | | `receipt connect device login expired` | The code lives 10 minutes and you passed it | Run the command again and approve promptly | | `receipt connect device login timed out` | The CLI polled for its full 10 minutes without an approval | Run the command again | | `receipt connect device login returned an empty token` | The server approved but returned nothing usable | Retry; if it repeats, it is an operator problem | | `receipt connect login did not return a workspace; select a Receipt workspace and try again` | The browser session that approved the CLI has no active organization | Open Receipt, select a workspace, then re-run the command | The approval page has its own messages. **`Select a workspace first`** appears with `Receipt Connect credentials are stored at the workspace level. Open Receipt, select a workspace, then run the CLI command again.` — the browser half of the workspace error above. **`This Receipt Connect code is invalid or expired.`** means the code is unknown or past its ten minutes. **`This Receipt Connect code was already used. Run the CLI command again.`** means you approved the same code twice; each one is single-use. A successful approval reads `Receipt Connect is approved`, with `You can return to the terminal. This page can be closed.` ## Sessions and authorization | Message | Cause | Fix | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------ | | `receipt workspace: not signed in; run 'receipt setup' first` | No saved session, or `--target` names one that was never created | Run `receipt setup`. `receipt workspace --help` produces this too, because these commands do not print help | | `receipt mcp: not signed in; run 'receipt setup' first` | The same, from `receipt mcp` **and** from `receipt tools` — both share the identity resolver, so `tools` inherits the `receipt mcp:` prefix | Run `receipt setup` | | `Receipt Connect gateway is unavailable; run 'receipt setup' or set RECEIPT_CONNECT_TOKEN` | `receipt connect list`, `tools` or `call` with no session and no environment identity — or `RECEIPT_CONNECT_TOKEN` set with no `RECEIPT_CONNECT_GATEWAY_URL`, which suppresses the saved session | Sign in, or set both variables together | | `Receipt Connect task token is unavailable; run 'receipt setup' or set RECEIPT_CONNECT_TOKEN` | A gateway URL is set in the environment but no token is | Set `RECEIPT_CONNECT_TOKEN`, or unset the gateway variable so the saved session is used | | `unauthorized` from `workspace`, `tools` or `mcp` | The 12-hour token expired or was revoked. These commands do not check the expiry themselves, so the gateway is the first to notice | `receipt doctor` marks the session `EXPIRED`; run `receipt setup`, or `receipt setup --fresh-login` to force a new login | | `Saved Receipt session was rejected by the gateway; signing in again.` followed by success | Not an error. `receipt connect status`, `disconnect` and provider onboarding retry a rejected token once by signing in again | Nothing | | `Receipt could not authenticate this task. Its runtime access token must be renewed before retrying.` (HTTP 401, code `receipt_connect_runtime_authentication_required`) | The gateway rejected the token on a tool listing or call | Run `receipt setup`. Inside a sandboxed run, the task token must be reissued | | `Receipt could not authorize this task to use the connection. This is a task permission problem; reconnecting the account will not fix it.` (HTTP 403, code `receipt_connect_execution_scope_missing`) | The token can discover tools but not execute them | Use a CLI sign-in token, or a task token that carries execution scope. Reconnecting the provider changes nothing | | `workspace_membership_required` (HTTP 403) | The token's workspace is not one you are a member of, or you lack authority for the change | Run `receipt workspace use `, or ask an owner or admin | A session file that will not parse, or that is missing its gateway URL, token or organization id, is treated as **no session** rather than as an error — you get `not signed in` and the fix is `receipt setup`. A file the CLI cannot read at all, such as one with wrong permissions, is different: the read throws and the command exits `1` with the underlying error. Deleting `~/.receipt/session.json` and signing in again clears both. ## Connecting a provider | Message | Cause | Fix | | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | | `unsupported Receipt Connect onboarding choice: