Docs › Troubleshooting › Agent run problems
Agent run problems
Fix runs that stop early or loop, folders the agent cannot write to, refused commands, failing checks, and parallel agents that will not start.
On this page
- Stopped after N steps without finishing
- Stopped: the agent repeated the same call
- The model returned an empty reply twice
- The run stopped before finishing
- Open a folder for the agent to work in
- The agent cannot change files or run commands in this folder
- A command was refused because it needs a keyboard
- A command is asked about even in Never ask
- DENIED: the user did not approve
- UNAVAILABLE in a read-only mode
- A check fails on code the run did not touch
- The run card says Checks failed
- Checks take too long
- Tests miss the change
- Terraform or Pulumi apply refused
- An edit is refused while building a plan
- A path resolves outside the workspace
- Browser control is off
- Starting agents is not available here
- Memories are switched off
- A debugger tool is only available in Debug mode
- Parallel agents do not start
- Undo left a file alone
- A background command keeps waking the chat
- The agent ignores the project's rules
How runs work is on Agent overview, approvals on Approvals and permissions, and the checks on How the agent checks its work. Messages starting DENIED or ERROR below appear in the tool card the agent sees, and the agent usually tells you about them in its reply.
Stopped after N steps without finishing
Cause: the run reached its step limit, 150 by default. That usually means the task is broad, or the agent was going round in circles. The conversation is kept.
- Send another message, such as
continue, to carry on from where it stopped. - Or narrow the request to one part of the work.
- Or raise the limit: AstraCode Settings > Agents > Step Limit (50, 150, 400 or 1000), which is
astracode.agent.maxSteps.
Stopped: the agent repeated the same call
The run ends with Stopped: the agent repeated the same tool call a number of times without making progress.
Cause: the same call was made four times in a row with the same result, so the run stopped rather than spend your allowance on it.
- Read the last few tool cards to see what it kept trying.
- Send a message with the fact it was missing, or rephrase the request. The conversation is kept.
The model returned an empty reply twice
The run stopped. The conversation is kept.
- Send
continueto try again. - If it repeats, start a new chat and report it with AstraCode: Report a Problem.
The run stopped before finishing
The run ends with The run stopped before finishing: followed by an error, or a failure card.
- Read the card's title. Usage, billing and connection cards are explained in Usage, billing and network errors.
- Send the message again once the cause is fixed. The conversation is kept.
The provider is rate limiting; waiting a number of seconds and retrying is not an error: the run waits and carries on by itself.
Open a folder for the agent to work in
Cause: Agent and Debug mode change files in a folder, and this window has none open. Your message is put back in the box.
- Choose Open Folder, or New folder to create one.
- Send the message again in the window that opens. Your draft goes with it.
Ask mode works without a folder.
The agent cannot change files or run commands in this folder
Tool cards show DENIED: a tool is disabled in an untrusted folder.
Cause: you have not trusted this folder. Reading and answering still work; writing files, running commands and project connectors do not.
- Run Workspaces: Manage Workspace Trust from the command palette.
- Trust the folder, if you trust its authors.
- Send the message again.
More in Workspace trust.
A command was refused because it needs a keyboard
The tool card says the command was not run: commands here have no keyboard, so it would wait until the timeout.
Cause: the command is interactive, such as an editor, a pager, a bare REPL, git commit without -m, git rebase -i, a create command without -y, or a login.
- The agent usually retries with the non-interactive form on its own.
- To run it yourself, type
!and the command in the composer; it runs in your project and the output goes to the agent with your next message. For a login, run it in your own terminal.
A command is asked about even in Never ask
The approval card carries a warning that ends Confirmed even in autonomous mode.
Cause: some actions are always confirmed, whatever the approval setting: any git push, publishing a package, rewriting published history, discarding uncommitted work, sudo, deploys and infrastructure changes, reading secrets files, installing a package the project does not declare, opening a page off this machine, saving a memory, and writes into .git/, .github/workflows/ or agent configuration. Always allow does not apply to them.
This is by design. Approve it when you mean it. The full list is on Approvals and permissions.
DENIED: the user did not approve
Cause: you chose Deny on an approval card. The agent is told and usually tries another way or asks you. To approve that kind of command from now on in this project, choose Always allow next time; remembered commands are listed under Approval in AstraCode Settings > Agents, each with Forget.
UNAVAILABLE in a read-only mode
Cause: Ask and Plan only read. They can run a short list of read-only commands, and refuse anything else.
- Switch to Agent with the mode control, or press Cmd+. (Ctrl+. on Windows and Linux) to cycle modes.
- Send the request again.
A check fails on code the run did not touch
The chat shows a check command followed by fails on code this run did not touch; moving on.
Cause: the project's own check was already failing before the run, in files the run did not change. The run does not try to fix it.
- Fix the existing failure separately.
- Or point the check at a command that passes today with
astracode.agent.verifyCommand.
The run card says Checks failed
Cause: the project's checks still failed after the agent's attempts to fix them, or the independent evaluator found problems the agent could not fix.
- Read the reply: it says what is still failing.
- Send a message to continue, with anything the agent needs to know.
- Or choose Undo on the run card to put every file back.
Checks take too long
- Set
astracode.agent.verifyCommandto a faster command, such as your unit tests only. - Or turn off
astracode.agent.verify. The evaluator still reviews the change.
Tests miss the change
Cause: with the run's code changes taken away for a moment, the tests still passed, so they do not test the change. The run is sent back once to write a test that does; if the chip remains, the new test still does not catch it.
Ask for a test that fails without the change, or turn the check off with astracode.agent.sabotageCheck.
Terraform or Pulumi apply refused
The tool card says ERROR: run `terraform plan` first (or pulumi preview).
Cause: an apply is refused unless a plan or preview succeeded earlier in the same run, so you can read what will change before you approve it.
- Let the agent run the plan, for example
terraform plan -out tfplan. - Read the summary of what it creates, changes and destroys.
- Approve the apply. See Infrastructure as code.
An edit is refused while building a plan
The tool card says a file is not one of the files the active step names, or that no step is active.
Cause: while a plan is built, each step may change only the files its (files: ...) tag names.
- Open the plan with View Plan.
- Add the file to the step's
(files: ...). A path ending in/covers everything under it. - Continue the build. See Plan mode.
A path resolves outside the workspace
Cause: the agent works only inside the open folders. To let it work in another repository, add that folder to the workspace. See Working across several repositories.
Browser control is off
The tool card says DENIED: browser control is off.
- Open AstraCode Settings > Browser & Network.
- Turn on Agent Browser Control (
astracode.browser.control.enabled). - Ask again. See Browser tools.
Starting agents is not available here
Cause: subagents are switched off (astracode.agent.subagents), or the nesting limit was reached (astracode.agent.maxAgentDepth). The agent does the work itself. See Subagents and background tasks.
Memories are switched off
Cause: astracode.memories.enabled is off, so nothing was saved. Turn it on to let the agent remember. See Memories.
A debugger tool is only available in Debug mode
Cause: the debugger tools run only in Debug mode, inside the editor. Switch to Debug with the mode control. See Debug mode.
Parallel agents do not start
| Message | Fix |
|---|---|
| Open a folder to run parallel agents. | Open the repository's folder first. |
| Parallel agents need a git repository: each one works in its own worktree. | Run git init and make a first commit, or open the repository's root folder. |
| Agent N could not get a worktree and was not started. | Check the AstraCode Agent log for git's reason; a dirty or locked worktree under .astracode/worktrees is the usual one. The other agents carry on. |
Parallel agents run from the button beside Send in Agent mode only. See Running several agents at once.
Undo left a file alone
The run card says Left alone: a file has changed since the agent wrote it.
Cause: you or something else changed the file after the run, so undoing would lose that change. Put it back by hand, or restore a checkpoint. See Checkpoints and undo.
A background command keeps waking the chat
When a command the agent started in the background ends after the run, the agent is woken to react, at most three times in a row without a message from you. To stop it, turn off astracode.agent.wakeOnBackgroundEnd.
The agent ignores the project's rules
- The folder is not trusted: rules are not read in an untrusted folder.
astracode.projectRulesis off..astracode/rules.mdexists: it replacesAGENTS.mdentirely.- The rules file is over 8,000 characters and was cut off.
See Rules.
← Chat panel problems Connector 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