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

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.

  1. Send another message, such as continue, to carry on from where it stopped.
  2. Or narrow the request to one part of the work.
  3. 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.

  1. Read the last few tool cards to see what it kept trying.
  2. 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.

  1. Send continue to try again.
  2. 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.

  1. Read the card's title. Usage, billing and connection cards are explained in Usage, billing and network errors.
  2. 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.

  1. Choose Open Folder, or New folder to create one.
  2. 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.

  1. Run Workspaces: Manage Workspace Trust from the command palette.
  2. Trust the folder, if you trust its authors.
  3. 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.

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.

  1. Switch to Agent with the mode control, or press Cmd+. (Ctrl+. on Windows and Linux) to cycle modes.
  2. 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.

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.

  1. Read the reply: it says what is still failing.
  2. Send a message to continue, with anything the agent needs to know.
  3. Or choose Undo on the run card to put every file back.

Checks take too long

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.

  1. Let the agent run the plan, for example terraform plan -out tfplan.
  2. Read the summary of what it creates, changes and destroys.
  3. 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.

  1. Open the plan with View Plan.
  2. Add the file to the step's (files: ...). A path ending in / covers everything under it.
  3. 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.

  1. Open AstraCode Settings > Browser & Network.
  2. Turn on Agent Browser Control (astracode.browser.control.enabled).
  3. 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

MessageFix
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

See Rules.

← Chat panel problems Connector problems →

All documentation

Get started

Using the editor

Agent

Context

Workspaces

Connectors

Extending AstraCode

CLI

Account and usage

Troubleshooting

Reference