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 wrong | Page |
|---|---|
| Signing in fails, never finishes, or you keep being signed out | Sign-in problems |
Installing, the astra command, or an update fails | Install and update problems |
| The chat panel is blank, crashed, stuck, or a message did not send | Chat panel problems |
| The agent stops early, loops, refuses a command or cannot write | Agent run problems |
| A connector will not start, sign in, or answer | Connector problems |
| The microphone is blocked or nothing is heard | Dictation problems |
| A usage limit, billing message, or a connection error | Usage, billing and network errors |
astracode-agent in a terminal, script or CI | CLI problems |
First checks
Most problems are solved by one of these. Try them in order:
- 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.
- Can the editor reach AstraCode? It needs
api.astracode.ioandastracode.io. A VPN, proxy or firewall that blocks either one breaks chat, sign-in and updates. - Are you on the current version? Run AstraCode: Check for Updates. Many problems are fixed in a newer build.
- 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.
- Reload the window. Run Developer: Reload Window from the command palette. Your chats are kept.
- 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.
| Log | What is in it | How to open it |
|---|---|---|
| AstraCode Agent | Agent runs, requests to the gateway, errors and the chat panel | AstraCode: Show Agent Log, or Agent log in the chat's More menu (the three dots at the top of the chat) |
| AstraCode MCP | Connectors and their sign-in, updates and first-run setup | AstraCode: MCP: Show Connection Log, or Connection log in AstraCode Settings > Customize > MCP servers |
| AstraCode Hooks | Every hook that ran, with its exit code and output | Open 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
- 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