Docs › Troubleshooting › CLI problems
CLI problems
Fix sign-in, trust, network, search, undo, update and plugin problems with astracode-agent.
On this page
- Not signed in
- Signing in over SSH or in a container
- Sign-in timed out, was declined, or was cancelled
- Your session has expired
- Could not save to the Keychain
- Another sign-in is already waiting
- Unable to connect to AstraCode
- The folder is not trusted
- Unknown command
- Content search is unavailable
- Nothing to undo, or no run with that id
- review cannot find what to compare against
- Usage errors (exit code 2)
- Update problems
- Plugin was not installed
- Zed or JetBrains: the agent will not change files
Errors from astracode-agent start with astracode-agent:. For the full technical detail of an unexpected error, run the command again with ASTRACODE_DEBUG=1 set. The commands and flags are on the CLI reference.
Not signed in
Not signed in. Run astracode-agent login, or set ASTRACODE_API_KEY. With -p and review the exit code is 2.
- Run
astracode-agent loginand approve in the browser. - In CI, set
ASTRACODE_API_KEYinstead. See Scripts and CI. - Check with
astracode-agent status.
Signing in over SSH or in a container
Cause: the browser hands sign-in back to 127.0.0.1 on the machine that opened it, which over SSH or in a container is the wrong machine.
- Run
astracode-agent login --code. Over SSH this is chosen for you. - Open the printed link in a browser on any device and approve.
- Copy the code the page shows and paste it at the
Code:prompt. - The CLI says
Signed in.and where the session is saved.
If the code is refused, the CLI adds (a code works once, for five minutes). Run astracode-agent login --code again and paste the new code within five minutes. For CI, use ASTRACODE_API_KEY instead.
Sign-in timed out, was declined, or was cancelled
sign-in timed out waiting for the browser, sign-in was declined in the browser, sign-in was cancelled or sign-in was not completed, each followed by Run astracode-agent login to try again.
- Run
astracode-agent loginagain and approve within 30 minutes. - If the browser cannot reach this machine, use
login --code.
Your session has expired
Your session has expired. or Your session has ended. A session lasts 36 hours and is renewed as you use the CLI. Run astracode-agent login.
A run that stops with You are signed out has the same fix: run astracode-agent login, or check that ASTRACODE_API_KEY holds a current key.
Could not save to the Keychain
could not save to the Keychain: followed by a reason, on macOS.
- Unlock your login keychain, then sign in again.
- Or set
ASTRACODE_CONFIG_DIRto a folder: the session is then saved incredentials.jsonthere, readable only by you.
Another sign-in is already waiting
Finish or close the sign-in already open in your browser, then try again.
Unable to connect to AstraCode
On first run: Could not reach the gateway, Check your internet connection, a proxy or VPN, and try again. During a run: Could not reach AstraCode, with the reason.
- Check the connection, and that a VPN or proxy allows
api.astracode.io. - If you use your own gateway, check
ASTRACODE_GATEWAY_URL. - Run the command again.
The reasons and the other gateway cards are the same as in the editor: see Usage, billing and network errors.
The folder is not trusted
Tool results say a tool is disabled in an untrusted folder, and the agent reads and answers but does not change files or run commands.
- Run
astracode-agentin the folder and answer Yes, I trust this folder on first run. It is remembered. - Or pass
--trustfor one run, or setASTRACODE_TRUST=1. - In the line-at-a-time session (when input is not a terminal), type
/trust. -palways trusts its folder.reviewandacpneed--trust.
Answering No, exit to the trust question on first run quits with exit code 1. See Workspace trust.
Unknown command
Unknown command / followed by a name. Type /help for the commands in the conversation. /trust is not one of them in the full-screen conversation; see the section above.
Content search is unavailable
A tool result says content search is unavailable (ripgrep not found in this build).
- Install ripgrep (
rg) with your package manager. - Make sure
rgis on your PATH, then run again.
Nothing to undo, or no run with that id
no runwith an idhere; astracode-agent undo --list shows them: runastracode-agent undo --listand use an id it shows, from the same folder (or pass--cwd).nothing to undo ina folder: no run recorded changes there. Checkpoints need git on your PATH; without it, runs carry on but cannot be undone.Left alone, changed since:the files listed changed after the run, so they were not put back.
review cannot find what to compare against
| Message | Fix |
|---|---|
is not inside a git repository | Run it inside the repository, or pass --cwd. |
cannot find a common ancestor of HEAD and a base | In CI, check out with fetch-depth: 0. |
could not work out what to compare against; pass --base <ref> | Pass --base main, or the branch you compare with. |
See Reviewing a branch.
Usage errors (exit code 2)
the prompt is emptyorthe prompt on stdin is empty: give-pa prompt.- A folder
is not a directory: check--cwd. --continue and --resume open a conversation; they do not apply to -p.- A flag that applies only to
-p, such as--permissions, given to a conversation. --agents: the value isneither JSON nor a file that can be read, or an agentneeds a descriptionorneeds a prompt.--agent:there is no agent calledthat name; the message lists the ones there are.
Update problems
could not check for updates:followed by a reason: check the connection.a proxy needs you to sign in to it (HTTP 407)means your proxy needs credentials.could not fetch the installerorcould not run the installer: run the install command from AstraCode CLI again.- Installed with Homebrew or npm,
astracode-agent updateprints the command to run instead:brew upgrade astracode-agentornpm install -g astracode-agent@latest. - The installer stops with
checksum mismatchor a signature error: nothing was installed. Run it again; if it repeats, report it.
Plugin was not installed
A plugin was not installed: it runs the commands above, and nobody was asked.
- Read the commands the plugin would run, printed above the message.
- Run the install again with
--yesif you accept them.
A sensitive plugin option is never taken from the command line: run astracode-agent plugin config with the key and no value, and type it or pipe it in. See Plugins.
Zed or JetBrains: the agent will not change files
Cause: acp treats the folder as untrusted unless told otherwise, and in an untrusted folder edits and commands are refused outright.
- Run the full-screen
astracode-agentin that folder once and trust it. - Or add
--trustto the command your editor runs, which trusts every folder it opens, or setASTRACODE_TRUST=1.
See Zed and JetBrains.
← Usage, billing and network errors Settings reference →
All documentation
Get started
Using the editor
- Tab completion
- Edit and ask about a selection
- Reviewing the agent's changes
- Git: commit messages, branch review and conflicts
- Dictation
- Layout, themes and the settings page
Agent
- Agent overview
- Agent, Plan, Ask and Debug
- Approvals and permissions
- Plan mode
- Debug mode
- Tools
- Browser tools
- How the agent checks its work
- Checkpoints and undo
- Running several agents at once
- Subagents and background tasks
- Remote agents in GitHub Actions
- Infrastructure as code
Context
Workspaces
Connectors
- Connectors (MCP servers)
- Connector configuration reference
- Use AstraCode from Claude, ChatGPT and other apps
Extending AstraCode
CLI
Account and usage
- Usage and limits
- Bring your own key
- What AstraCode sends and keeps
- Reporting a problem and getting help
Troubleshooting
- Troubleshooting
- Sign-in problems
- Install and update problems
- Chat panel problems
- Agent run problems
- Connector problems
- Dictation problems
- Usage, billing and network errors
- CLI problems