Skip to main content
Most CLI problems are one of five things: you are not signed in, the coding service is unreachable, a host is not connected, a permission or mode is narrower than you think, or a run hit a limit. This page is ordered by the message or symptom you actually see, so you can jump to the one in front of you. Start with the diagnostic block below whatever the symptom is. It takes ten seconds and it answers most of the follow-up questions before you have to ask them.

​
Start with six commands

cortex debug config is the one people forget. It shows the configuration in effect after your profile, your project file and any -c overrides have been merged, which is usually where a surprising behaviour comes from. cortex debug config --diff narrows it to where your project file and your profile disagree, and cortex debug config --env adds the Cortex environment variables that are influencing the result.
-v and --trace raise console verbosity for a single run, and that output can include the contents of your prompts and files. --debug is the safer switch: it records bounded, content-free diagnostics under the Cortex home diagnostics/ directory, or the directory named by CORTEX_DIAGNOSTICS_DIR. Each entry carries eight fields and nothing else: schema, timestamp, version, operation, trace_id, span_id, status and duration_ms. There is no prompt text, no file content, no path and no account identifier, because the recording API takes no user-supplied string at all. A journal file stops at 2 MiB, the directory keeps at most 64 of them, entries older than 7 days are pruned, and on Unix-like systems the files are written owner-read-write only. It never overwrites ./debug.txt, and it never uploads anything.

​
The service, the host, and signing in

​
The coding service is temporarily unavailable

This means the CLI could not reach the coding service. The message is deliberately the whole story: the CLI does not name a provider, an SDK or a transport, so there is nothing further hidden behind it. Four checks, in order:
  1. Can you reach api.cortex.foundation from this machine?
  2. Is a proxy in the way? HTTPS_PROXY and HTTP_PROXY are honoured for cortex scrape, but corporate TLS interception can still break other calls.
  3. Is CORTEX_API_URL set to something unexpected? cortex debug config --env will tell you.
  4. Are you signed in? Run cortex whoami.
If all four look right, check status.cortex.foundation before digging further.

​
This PC and SSH Code execution require an already connected Code session

You selected This PC or SSH, with CORTEX_COMPUTER or CORTEX_SSH_HOST, without a connected Cortex Code session. Those hosts are never created on the fly, and Cloud is not quietly substituted, because running your tools somewhere other than where you asked is worse than refusing. Either resume a session that already has a host, or unset CORTEX_COMPUTER to use Cloud. See Cloud, This PC, and SSH.

​
Sign-in does not complete

Device and single sign-on flows, expired credentials, and headless machines with no browser are covered on Sign in. cortex login status reports where you stand, and cortex whoami shows the account a run will use.

​
The interface will not start

The CLI needs a terminal on both standard input and standard output. In a pipeline, a CI job, or under a wrapper that redirects either one, it refuses to start and points you at cortex run or cortex exec. That is the fix, not a workaround: see Headless and scripting and CI and automation.

​
The agent will not change anything

Work down this list in order. One of the six is almost always the answer, and cortex debug config --diff shows what differs from the defaults.
1

Check the mode

Plan mode is read-only by design. Press Shift+Tab to cycle to Agent. See Plan and Spec modes.
2

Check the sandbox

--sandbox read-only blocks all writes. workspace-write confines them to the workspace instead of forbidding them.
3

Check the approval policy

With --ask-for-approval never and no autonomy granted, the agent may be silently declining rather than prompting you.
4

Check the permission table

The [permission] table in config.toml can deny editing, or specific shell command patterns, outright. A project file can carry it too, and a project file beats your own. See Permission policy.
5

Check the agent

An agent defined with read-only tools cannot write, whatever the session policy says. cortex agent show <name> prints its definition.
6

Check for Spec mode

In Spec mode the mutating tools stay locked until the submitted plan is accepted.

​
A tool is not available

If a tool you expect is missing, something narrowed the set: the agent’s own tool list, the current mode, or the [permission] table. --enabled-tools and --disabled-tools are not the cause, because cortex exec accepts them only alongside --list-tools. Tools the agent uses lists the full set and what each one needs.

​
An MCP server is not connecting

Four causes account for most failures:
  • The local command is not on PATH in the environment the CLI launches it from.
  • A -- was missing from cortex mcp add, so the server’s own flags were parsed as CLI flags.
  • The URL points at localhost or a private range and needs --allow-local.
  • The bearer token environment variable named in the configuration is not set in the environment the CLI is running in.
MCP servers has the full add-and-authorise flow.

​
Runs, limits and output

​
A run times out

cortex exec defaults to a 600-second timeout and 100 turns. Raise both for a genuinely large task:
If a single shell command is the problem rather than the whole run, raise --command-timeout or execution.command_timeout_seconds instead. Breaking a large task into several smaller runs is usually better than raising the ceiling: each run starts with a clean context and you get to check the work in between.

​
Quota exhausted

When the quota for your plan runs out, the run stops and the composer is held: Add a follow-up — held until quota resets. Follow-ups you type queue until the window resets rather than being lost. /usage shows the detail. See Plans and quotas.

​
Output is truncated or mangled

  • Use --color never for logs and pipelines, or set NO_COLOR in the environment.
  • Use -o json or -o stream-json when something downstream parses the output. The shape of text output is not a contract, and it can change between releases; the JSON envelope is the stable surface.

​
Disk usage keeps growing

Lock the sessions you want to keep before you run a cleanup, so it skips them:
Data locations explains what lives where, and which directories are safe to delete by hand.

​
A build from source fails

On Linux, the optional audio and desktop components need ALSA headers, so install them and use the toolchain the repository pins:
The prebuilt binaries on software.cortex.foundation are the supported path for everyday use. See Install the CLI.

​
Report a problem

--include-logs attaches recent local log output to the report, so read it first if the run involved anything you would not want to share. Submissions queue in the Cortex home feedback/ directory when you are offline and go out on the next successful call. cortex feedback history shows what you have sent.
Include three lines from the diagnostic block in any report: the cortex --version output, whether cortex whoami resolves, and the platform line from cortex debug system. That trio answers the first round of questions on its own.