> ## Documentation Index > Fetch the complete documentation index at: https://docs.usecustory.com/llms.txt > Use this file to discover all available pages before exploring further. # CLI troubleshooting > Fix common Custory CLI authentication, setup, MCP, and JSON failures. Use this page when a CLI command fails, hangs, opens the wrong account, or returns output you do not understand. ## Start here Run these checks first: ```bash theme={null} custory doctor custory status custory workspace list node --version ``` If MCP is involved, also run: ```bash theme={null} custory mcp verify --client codex ``` Replace `codex` with `claude` or `cursor` when needed. ## Confirm which binary is running If the wrong or old CLI version appears to run, confirm the binary. On macOS or Linux: ```bash theme={null} which custory custory --version ``` On Windows PowerShell: ```powershell theme={null} Get-Command custory custory --version ``` You can bypass a global install with: ```bash theme={null} npx @custory/cli@latest --version ``` ## Node.js version is too old Cause: the CLI requires Node.js `22.12` or newer. Safe next action: 1. Install a supported Node.js version. 2. Open a fresh terminal. 3. Run `node --version`. 4. Run `custory doctor`. Retry after the runtime is supported. ## CLI discovery is unreachable Common codes: * `CLI_DISCOVERY_UNREACHABLE` * `DISCOVERY_UNREACHABLE` Cause: the CLI could not load `/.well-known/custory-cli.json` from the configured Custory app. Safe next action: 1. Check network or proxy access. 2. Remove `--app-url` unless Custory specifically told you to use it. 3. If using `--app-url`, confirm it points to the intended Custory app origin. 4. Run `custory doctor`. Retrying is safe after network or configuration changes. ## Custory service is unreachable or not ready Common doctor codes: * `SERVICE_UNREACHABLE` * `SERVICE_NOT_READY` Cause: discovery worked, but the CLI health check could not confirm that Custory's worker and backing services are ready. Safe next action: ```bash theme={null} custory doctor --json ``` Retry later. If it persists, share the redacted doctor report with Custory support. ## npm cannot find the package or version Cause: npm registry access, network configuration, cache state, or a mistyped package name. Safe next action: ```bash theme={null} npm view @custory/cli version npx @custory/cli@latest --version ``` Confirm the package name is exactly `@custory/cli`. Retry after network or registry access is working. ## Browser sign-in does not open Cause: the terminal could not launch a browser. Safe next action: ```bash theme={null} custory login --no-browser ``` Copy the printed `Visit` URL into your browser and complete sign-in. Retrying is safe. Common error codes: `AUTH_PROVIDER_UNREACHABLE`, `AUTH_START_FAILED`, `AUTH_EXPIRED`, `AUTH_DENIED`, `AUTH_TOKEN_FAILED`, `AUTH_CANCELED`. ## Browser sign-in does not complete Cause: the authorization flow expired, was canceled, or completed with a different account than expected. Safe next action: ```bash theme={null} custory login --force custory status ``` Use `--force` when you need to replace the active account. ## No workspace is available Cause: the signed-in account has no accessible workspaces, or you are signed in with the wrong account. Safe next action: ```bash theme={null} custory status custory workspace list ``` If the account is wrong, run: ```bash theme={null} custory login --force ``` If the account is right, ask a workspace owner to invite you or use `custory init` to create a new workspace when appropriate. ## Workspace name is ambiguous Cause: more than one accessible workspace matches the name you passed. Safe next action: ```bash theme={null} custory workspace list ``` Rerun the command with the workspace slug or ID instead of the display name. ## Website context is rejected or weak Cause: the page may be private, blocked, redirected unexpectedly, too large, too thin, or not a useful product explanation. Safe next action: * use a more focused public URL * use `--brief` with a private product summary * use `--stdin` from a reviewed agent-generated summary Website input blocks localhost, private-network addresses, sensitive account or legal routes, more than 4 redirects, responses larger than `1,500,000` bytes, and fetches that exceed `20` seconds. Do not force a weak source with `--yes` unless you are comfortable heavily editing the result. ## Setup was interrupted Cause: the terminal stopped during an active onboarding session. Safe next action: ```bash theme={null} custory init --resume ``` For scripts: ```bash theme={null} custory init --resume --yes --json ``` If the CLI says no unfinished setup exists or the session expired, start a new setup and check Custory for an existing journey before creating another one. ## A command says confirmation is required Cause: non-interactive setup reached a source or persona confirmation step without permission to continue. Safe next action: * rerun interactively with `custory init` * or rerun non-interactively with `--yes` only after reviewing the input source Low-confidence persona suggestions may require explicit confirmation. Common error code: `INPUT_REQUIRED`. ## MCP client cannot be detected Cause: the CLI found no supported client or more than one possible client. Safe next action: ```bash theme={null} custory mcp install --client codex --workspace "Acme" ``` Supported values are `codex`, `claude`, and `cursor`. Common error code: `MCP_CLIENT_REQUIRED`. ## MCP config is malformed Cause: Claude or Cursor config is not valid JSON, or the existing `mcpServers` field is not an object. Safe next action: 1. Open the config file. 2. Fix the JSON. 3. Rerun `custory mcp install --client codex --workspace "Acme"` with the right client and workspace. The relevant config files are: * Codex: `~/.codex/config.toml` * Claude: `~/.claude.json` * Cursor: `~/.cursor/mcp.json` Common error code: `MCP_CONFIG_INVALID`. ## MCP verification fails Cause: the MCP credential, endpoint, workspace binding, or client config could not be validated. Safe next action: ```bash theme={null} custory mcp install --client codex --workspace "Acme" custory mcp verify --client codex ``` Reinstalling replaces the Custory MCP entry and revokes the previous tracked credential when possible. Common error codes: `MCP_NOT_INSTALLED`, `MCP_UNREACHABLE`, `MCP_VERIFICATION_FAILED`, `MCP_WORKSPACE_BINDING_INVALID`, `MCP_BINDING_INVALID`. ## Machine-readable partial results Cause: a command completed with warnings or a tool returned `success: false`. Safe next action: * inspect the JSON result * check `warnings` * open the returned journey URL when one exists * treat exit code `5` as partial success * treat exit code `4` as a recoverable or tool-level failure that needs review Do not discard partial results automatically. They may include a usable journey or a clear recovery path. ## Safe information to share with support Safe: * CLI version * command name * error code * `custory doctor` output after removing private IDs * whether the command used website, brief, or stdin input Do not share: * tokens * credentials * device codes * private brief contents * private customer data * raw MCP authorization headers ## Next step If the issue is fixed, return to [CLI quickstart](/cli/quickstart). If you are automating the CLI, read [Automation and JSON](/cli/automation).