Docs › Troubleshooting › Troubleshooting

Troubleshooting

Find the right troubleshooting page, read the logs, and run the checks that solve most problems.

On this page

Each troubleshooting page lists problems by the message you see, with what causes it and the steps that fix it. Search for the exact words on your screen, or start from the table below.

Find the right page

What is wrongPage
Signing in fails, never finishes, or you keep being signed outSign-in problems
Installing, the astra command, or an update failsInstall and update problems
The chat panel is blank, crashed, stuck, or a message did not sendChat panel problems
The agent stops early, loops, refuses a command or cannot writeAgent run problems
A connector will not start, sign in, or answerConnector problems
The microphone is blocked or nothing is heardDictation problems
A usage limit, billing message, or a connection errorUsage, billing and network errors
astracode-agent in a terminal, script or CICLI problems

First checks

Most problems are solved by one of these. Try them in order:

  1. Are you signed in? AstraCode Settings > General shows your account. If the composer's send button reads Log in, you are not. Run AstraCode: Sign In.
  2. Can the editor reach AstraCode? It needs api.astracode.io and astracode.io. A VPN, proxy or firewall that blocks either one breaks chat, sign-in and updates.
  3. Are you on the current version? Run AstraCode: Check for Updates. Many problems are fixed in a newer build.
  4. Is the folder trusted? In a folder you have not trusted, the agent reads and answers but does not change files or run commands. See Workspace trust.
  5. Reload the window. Run Developer: Reload Window from the command palette. Your chats are kept.
  6. Is the chat panel blank? Run AstraCode: Repair the Chat Panel.

Read the logs

AstraCode writes three logs. Each is an output channel in the editor's Output panel, and each records detail the messages leave out.

LogWhat is in itHow to open it
AstraCode AgentAgent runs, requests to the gateway, errors and the chat panelAstraCode: Show Agent Log, or Agent log in the chat's More menu (the three dots at the top of the chat)
AstraCode MCPConnectors and their sign-in, updates and first-run setupAstraCode: MCP: Show Connection Log, or Connection log in AstraCode Settings > Customize > MCP servers
AstraCode HooksEvery hook that ran, with its exit code and outputOpen the Output panel with View: Toggle Output and pick AstraCode Hooks in its list. It exists once a hook has run.

Update problems are logged in AstraCode MCP, not in the agent log. It is named after connectors, but it is also where updates and first-run setup write.

Failure cards in the chat end with a Reference line. Include it when you contact support: it identifies the request on our side.

Still stuck

Run AstraCode: Report a Problem. It writes up what happened from the log, shows you everything before sending, and gives you a ticket number. See Reporting a problem and getting help.

← Reporting a problem and getting help Sign-in problems →

All documentation

Get started

Using the editor

Agent

Context

Workspaces

Connectors

Extending AstraCode

CLI

Account and usage

Troubleshooting

Reference