Getting Started
Licensing
System Requirements
Agents / AI Coding Agent Troubleshooting
New to FORGE? Start a free 30-day trial

AI Coding Agent Troubleshooting Guide

Updated on Oct 5, 2026

Use this guide when Forge cannot find or authenticate your AI coding agent, cannot load the agent configuration, or fails while the agent runs. Each entry starts with the symptom or exact message. For installation and configuration steps, see AI Coding Agent Setup.

Start with diagnostics

  1. From the project root, check the project, agent, and toolchain:
bash
frg status --verbose

The output shows the detected project root, the coding agent with its installation and authentication status, any Configuration Warnings:, the toolchain status, and Validation completed in <time>.

  1. Validate the agent configuration:
bash
frg config validate --file .forge/config/agents.toml
  1. Reproduce the failure and watch the agent live. --tail needs an active job context:
bash
FORGE_ISSUE_ID=42 frg --tail

See Tail Troubleshooting.

  1. Read the trace files for the job in .forge/work/<job_dir>/traces/.

  2. For more detailed logs, set RUST_LOG:

bash
RUST_LOG=debug frg issue draft
powershell
$env:RUST_LOG="debug"; frg issue draft
  1. To create a support package, run:
bash
frg diagnose --bundle --include-traces --include-logs --output frg-support.tar.gz

--include-traces and --include-logs add files from the last 24 hours. Use frg diagnose --format json for machine-readable output. See frg diagnose. Remove secrets and confidential prompt content before you share the bundle.

Installation

is not installed or not found in PATH

frg status shows Coding Agent: not installed, followed by this error. For GitHub Copilot the message includes installation hints:

text
Agent error: GitHub Copilot CLI is not installed or not found in PATH.

Installation:
- Via npm: npm install -g @github/copilot
- Via your package manager

Cause: Forge cannot run the agent's default command (copilot, claude, or opencode) with --version.

Solution:

  1. Install the agent. See Install an agent.
  2. Run the command directly, for example copilot --version.
  3. Add the executable's folder to PATH, or set an absolute command in [agent.<id>].

Verify: frg status --verbose shows the agent name followed by (installation check: <time>).

is not installed or not accessible with Configured command:

Cause: The command override in agents.toml points to a path that does not exist or cannot run.

Solution:

  1. Check the command path in .forge/config/agents.toml.
  2. Make sure the command is in your PATH, or use an absolute path. On Windows, escape backslashes (C:\\path\\to\\copilot.exe) or use forward slashes.
  3. Test the command manually with --version.
  4. Run frg status.

'command = "gh"' is not supported.

Full message:

text
Configuration error for agent 'github_copilot': 'command = "gh"' is not supported.

The 'gh copilot' wrapper has Windows command-line length limitations that cause failures with complex prompts.

Cause: agents.toml sets the GitHub CLI wrapper as the GitHub Copilot command.

Solution:

  1. Remove the command = "gh" line from .forge/config/agents.toml. Forge detects the installation automatically, including npm installs.
  2. Or install the standalone CLI with winget install GitHub.Copilot or npm install -g @github/copilot.
  3. Or set an explicit path, such as command = "C:\\path\\to\\copilot.exe".

Verify: frg config validate --file .forge/config/agents.toml reports agents.toml — valid.

Note: The dependency check in frg config validate can still print Install with: gh extension install github/gh-copilot. Ignore that hint and install the standalone CLI instead.

CLI not found. Install from: https://code.claude.com/docs/en/setup

Cause: Claude Code is selected, but claude is not installed or not in PATH.

Solution:

  1. Install Claude Code. See Claude Code CLI.
  2. Run claude --version.
  3. Run frg status --verbose.

Authentication

(not authenticated) in frg status

For GitHub Copilot, Forge reports:

text
GitHub Copilot CLI is not authenticated.

To fix:
1. Run: gh auth login
2. Follow the authentication prompts
3. Verify with: frg status

For Claude Code, the error includes the agent's exit code and output, for example Claude Code CLI authentication failed (exit code 1), or is not authenticated: detected '<text>' in output. Set ANTHROPIC_API_KEY environment variable.

Cause: The agent's authentication check failed. The session may have expired, the credentials may be missing, or the subscription may be inactive. Forge does not store or refresh agent credentials.

Solution:

  1. Authenticate the agent as the same user that runs Forge:
  • GitHub Copilot: run copilot and use /login, or set COPILOT_GITHUB_TOKEN to a fine-grained token with the Copilot Requests permission.
  • Claude Code: sign in, or set ANTHROPIC_API_KEY in the environment that runs Forge.
  • OpenCode: complete the provider login.
  1. Test the agent directly with a short prompt, for example claude -p "hello" or opencode run hello.
  2. Run frg status --verbose.

Verify: The status line shows Status: authenticated (auth check: <time>).

frg status reports not authenticated after you set a model

Symptom: frg status reports the agent as not authenticated, but the agent CLI works normally when you run it yourself.

Cause: frg status sends its authentication check using the agent-level model you set in .forge/config/agents.toml. If your agent CLI does not recognize that model name, the CLI returns an error that Forge cannot distinguish from a sign-in failure.

Solution:

  1. Run frg config validate. Forge reports a warning when a configured model name is not in its known list for that agent.
  2. Confirm the model name against your agent CLI's own model list.
  3. Correct the model value in .forge/config/agents.toml, or remove it so the check sends no model name and the agent CLI uses its own default.

Claude Code users: prefer correcting model to a current, valid value over removing it. Older Claude Code CLI versions fall back to an internally retired model ID when no --model flag is sent, which fails authentication for an unrelated reason (a 404 on the retired model, not a sign-in problem). If you remove model and authentication still fails, upgrade the Claude Code CLI to a version that no longer references retired model IDs.

Verify:

bash
frg status --verbose

Set FORGE_LOG=debug to see which model Forge used for the check, or that no model name was sent because none is configured.

(transient failure) or (service degraded) in frg status

With (transient failure), Forge also prints The auth probe hit a transient error. Retry the command or check upstream service health.

Cause: The authentication check hit a timeout, a rate limit, or a server error instead of a credential problem. Forge reports these separately from authentication failures, so you do not need to log in again.

Solution:

  1. Wait, then run frg status --verbose again.
  2. Check the agent provider's service status page.
  3. If the failure persists, test the agent directly with a short prompt.

Note: If the authentication check times out, Forge assumes the agent is authenticated and continues. A slow agent can therefore pass frg status and fail later during the workflow.

Configuration

Agent configuration required

text
Agent configuration required

No agents.toml file found at: <config-path>

Run the following command to configure your AI agent:
 frg config init --agent <AGENT_NAME>

Cause: A workflow command ran in a project without .forge/config/agents.toml, or outside the project root.

Solution:

  1. Change to the project root.
  2. Generate the configuration:
bash
frg config init --agent claude_code

Replace claude_code with github_copilot or opencode if needed.

Verify: frg status --verbose shows the agent you configured.

Forge uses GitHub Copilot instead of the configured agent

Cause: One of the following:

  • agent.default names an unknown agent, for example a misspelled ID or an agent that is no longer supported. Forge falls back to GitHub Copilot, and frg config validate still reports the file as valid.
  • agents.toml has a TOML syntax error or no [agent] default. frg config validate lists agents.toml — absent, and Forge uses GitHub Copilot.
  • The command passes --agent.

Solution:

  1. Set default to claude_code, github_copilot, or opencode, spelled exactly.
  2. Check the TOML syntax, including brackets and quotes, and make sure schema_version and [agent] default are present.
  3. Remove --agent from the command, or set it to the agent you want.

Verify: frg config validate --file .forge/config/agents.toml lists agents.toml — valid, and frg status --verbose shows the expected agent.

Empty command string for agent '' or contains shell operators

Cause: A command value is empty or contains shell operators such as && or ||. Validation marks agents.toml as invalid.

Solution:

  1. Remove the command line, or set it to a single executable name or absolute path.
  2. Put wrapper logic in a script and point command at the script.

Validation warnings about models or custom agents

frg status --verbose lists these under Configuration Warnings:, and frg config validate lists them under Warnings:. They do not block execution.

Cause and solution:

  • Model warnings about an empty, overlength, or structurally invalid name: see Model name validation. Forge does not warn based on a vendor model catalog; the agent CLI reports unavailable models.
  • Custom-agent warnings (Empty custom agent string, Invalid custom_agent_operations key): see Custom agent troubleshooting.

TOML parsing error, Invalid configuration at, or Validation error

Cause: A configuration file has invalid TOML (TOML parsing error: <message>), an invalid value at a known location (Invalid configuration at <file>:<line>: <message>), or a semantic problem (Validation error: <message>).

Solution:

  1. Open the file and line named in the error.
  2. Check quotes, brackets, table names, and value types. schema_version is required and agent.default is required mean a required key is missing.
  3. Run frg config validate again.

Toolchain: Missing (REQUIRED)

Cause: .forge/config/toolchain.toml does not exist. frg status still completes, but workflows that use the issue tracker or code platform cannot run.

Solution:

  1. Generate the toolchain configuration:
bash
frg config init --agent github_copilot --issues github_issues --code github

See Toolchain Configuration for other values.

Verify: frg status --verbose no longer shows Missing (REQUIRED).

Error: Prompt override file not found

text
Error: Prompt override file not found

Declared: [[prompt_overrides]] target="<target>" operation="<operation>" <role|task>="<name>"
Expected: <expected-path>

The configuration declares a custom <role|task> prompt, but the file doesn't exist.

Cause: .forge/config/commands.toml declares a prompt override, but the file does not exist at the expected path. The path depends on the selected prompt format.

Solution:

  1. Create the prompt file at the Expected: path, or run frg config export --prompts to export the built-in prompts.
  2. Or remove the [[prompt_overrides]] entry from .forge/config/commands.toml.
  3. If your files are in the other format, set prompt_format for the agent, target, or operation.

Verify: Run the command with --print-prompt to compile the prompt without running the agent.

Execution

Agent error: during a workflow

The error starts with Agent error:. It can include execution failed: and the agent's stderr after Agent stderr:.

Cause: The agent process exited with an error. Common causes are a model the provider does not offer, an expired session, a network failure, or a problem in the prompt or repository.

Solution:

  1. Read the complete error and the agent's stderr.
  2. Open the trace for the job in .forge/work/<job_dir>/traces/.
  3. Check the selected model, custom agent, and prompt format against your intended configuration.
  4. Test the agent directly with a short prompt.
  5. Fix the problem, then run the command again. If the agent finished but some outputs are missing, use --retry to continue the session instead of starting over.

Transient agent failures and automatic retries

A command pauses and then succeeds, or it fails with a message such as This error may resolve on retry. or This is likely a temporary issue with the agent's upstream service. The operation may succeed if retried.

Cause: The agent hit a transient error, such as a timeout, HTTP 429, a 5xx server error, service unavailability, or an invalid response. Forge retries these automatically with exponential backoff. It does not retry authentication failures or configuration errors, because retrying would not fix them.

Solution:

  1. Wait and run the command again.
  2. Check the provider's service status.
  3. Tune retries for your environment with FORGE_RETRY_MAX_ATTEMPTS, FORGE_RETRY_INITIAL_DELAY, FORGE_RETRY_MAX_DELAY, and FORGE_RETRY_BACKOFF_FACTOR, or turn them off with FORGE_RETRY_DISABLED. See Agent Retry.

operation timed out after or Command timed out after seconds

The agent-operation timeout message continues:

text
This may indicate:
- High system load during concurrent execution
- Network latency
- Temporary service slowness
Consider retrying or increasing timeout if this persists.

Cause: The agent or a shell step did not finish within its timeout. A timeout is different from an authentication failure. Your credentials are not the problem.

Solution:

  1. Check whether the agent is waiting for input or is blocked by the network.
  2. Run the command with frg --tail to see where it stops.
  3. Reduce the scope of the task, for example with --lite or a narrower --context-dir.
  4. Run the command again. Transient timeouts are retried automatically, as described in Transient agent failures and automatic retries.

Workflow failed in state:

Cause: A step in a stateful workflow failed. Usually the agent step failed, or an expected output is missing.

Solution:

  1. Read the preceding error and the trace for that state.
  2. Fix the cause.
  3. Resume from the failed step:
bash
frg workflow run <name> --start-from <state>

See Workflow Troubleshooting.

IO error:

Cause: Forge cannot create or write files under .forge/work/. The project folder may be read-only, the process may lack permission, or the disk may be full.

Solution:

  1. Confirm that you are in the intended project root (frg status shows Project Root:).
  2. Check the permissions:
bash
ls -ld .forge/work/
  1. Run Forge as a user that can write to the project folder. Ask your administrator before you change ownership or permissions recursively.

Verify: A new job folder and its traces/ folder appear under .forge/work/.

See Also

In this article
Start with diagnosticsInstallationis not installed or not found in PATHis not installed or not accessible with Configured command:'command = "gh"' is not supported.CLI not found. Install from: https://code.claude.com/docs/en/setupAuthentication(not authenticated) in frg statusfrg status reports not authenticated after you set a model(transient failure) or (service degraded) in frg statusConfigurationAgent configuration requiredForge uses GitHub Copilot instead of the configured agentEmpty command string for agent ' ' or contains shell operatorsValidation warnings about models or custom agentsTOML parsing error, Invalid configuration at, or Validation errorToolchain: Missing (REQUIRED)Error: Prompt override file not foundExecutionAgent error: during a workflowTransient agent failures and automatic retriesoperation timed out after or Command timed out after secondsWorkflow failed in state:IO error:See Also