Skip to main content
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:
If MCP is involved, also run:
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:
On Windows PowerShell:
You can bypass a global install with:

​
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:
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:
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:
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:
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:
If the account is wrong, run:
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:
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:
For scripts:
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:
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:
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. If you are automating the CLI, read Automation and JSON.