Agent Issues

Updated on Oct 1, 2026

Fixes for problems between Forge and the AI coding agent it launches: claude_code (Claude Code CLI), github_copilot (GitHub Copilot CLI), or opencode (OpenCode CLI). Forge has no API key of its own; it uses the agent's installation and login. For more agent-specific detail, see the AI Coding Agent Troubleshooting Guide.

Prerequisites

Run frg status --verbose first. It shows which agent Forge uses, whether it is installed, and whether it is authenticated.

Installation and discovery

<agent> is not installed or not found in PATH.

Example from frg status:

text

ℹ Coding Agent: not installed
 Error: 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

frg config validate reports the same problem as ⚠ GitHub Copilot CLI is not installed followed by Install with: gh extension install github/gh-copilot.

Cause

The agent CLI is not installed, or its directory is not on PATH, or command in .forge/config/agents.toml points to a path that does not exist.

Solution

Install the agent CLI. For GitHub Copilot CLI:

bash

npm install -g @github/copilot

For Claude Code and OpenCode, see Agent Setup.

Note: Ignore the gh extension install github/gh-copilot hint from frg config validate. Forge uses the npm package @github/copilot, and the gh copilot extension is not supported.

Check that the CLI runs:

bash

copilot --version

If it is not found, add the npm global bin directory to PATH:

bash

export PATH="$(npm config get prefix)/bin:$PATH"

If you set command in .forge/config/agents.toml, check that the path is correct, or remove the line so that Forge detects the CLI.

Verify

bash

frg status

command is not supported for GitHub Copilot invocation

Cause

.forge/config/agents.toml sets command = "gh". Forge does not run Copilot through the gh copilot wrapper. On Windows that wrapper also hits command-line length limits with long prompts.

Solution

Remove the command = "gh" line from agents.toml so that Forge detects the Copilot CLI.
On Windows, install the native CLI:

powershell

winget install GitHub.Copilot

An npm installation also works: Forge reads the copilot.cmd wrapper and runs the underlying script directly. 3. Or set an explicit path:

toml

[agent.github_copilot]
command = "C:\\path\\to\\copilot.exe"

Verify

bash

frg status

No default agent is configured

Cause

.forge/config/agents.toml is missing or has no default agent, and you did not pass --agent.

Solution

Create the agent configuration:

bash

frg config init --agent github_copilot

If agents.toml already exists, replace it:

bash

frg config init --agent github_copilot --force

Or pick the agent for one run:

bash

frg issue draft --agent claude_code

Verify

frg config show shows Default Agent: with your agent.

Authentication

GitHub Copilot CLI is not authenticated.

frg status shows (not authenticated) next to the agent, with the hint Run the agent's authentication command to authenticate.

Cause

The agent CLI is installed but not logged in, or its login or subscription has expired.

Solution

For GitHub Copilot CLI, run copilot and use the /login slash command. In CI, set COPILOT_GITHUB_TOKEN (or GH_TOKEN / GITHUB_TOKEN) to a fine-grained personal access token with the Copilot Requests permission.
For Claude Code or OpenCode, run the agent's own login command. See Agent Setup.
If your organization uses SSO, complete the SSO authorization in the browser.
Confirm that your account has an active Copilot subscription or model access.

Verify

bash

frg status

Authentication check timed out

text

Authentication check timed out - assuming authenticated (agent may be slow)

Cause

frg status and workflow commands run a short login probe against the agent. The probe did not answer in time, so Forge assumes the agent is logged in and continues. Forge reports a real timeout separately from an authentication failure.

Solution

If the command then works, no action is needed.
If the run fails with an authentication error, log in to the agent. See GitHub Copilot CLI is not authenticated.
If the agent is slow to start, for example on the first run after an update, give the probe more time:

bash

export FORGE_AGENT_AUTH_TIMEOUT_SECS=30

Execution

Agent exited with code <n>

Cause

The agent CLI started but ended with an error. Typical reasons are an invalid model name, an exhausted quota, or a crash inside the agent.

Solution

Open the latest trace in .forge/work/<job>/traces/ and read the ## Agent Stderr section.
If you passed --model, check that the agent supports that model. frg status lists available models.
Run the agent CLI on its own to see whether it works outside Forge:

bash

copilot --version

If stderr is cut off, raise the capture limits with FORGE_STDERR_LIMIT or FORGE_STDERR_MAX_LINES.

Agent run times out

Cause

The agent did not finish in time. Large context, a slow or degraded model service, and rate limiting are the usual reasons. Transient failures are retried automatically first; see Runtime Troubleshooting.

Solution

Reduce the context. Pass specific files with --context-file instead of whole directories.
Try the lightweight mode for simple changes:

bash

frg issue draft --lite

Check the provider's status page, for example https://www.githubstatus.com/ for GitHub Copilot.
If you are behind a proxy, configure it for the agent CLI. Forge calls the agent CLI, which makes the network requests.

Claude Code stops unexpectedly on Windows

Cause

The Claude Code process crashed before it finished writing its output.

Solution

Forge detects this, validates the agent output, and recovers automatically.
If expected files are still missing after the run, continue the same session:

bash

frg code create --retry

See Expected outputs are missing.

Sessions

Forge reuses agent sessions between related commands. See Session Context and Token Optimization.

Multiple sessions exist with name <name>

Cause

A previous command was cancelled before it completed and left a duplicate GitHub Copilot session. You may also be using sessions created with an older naming format.

Solution

Open the Copilot session picker:

bash

copilot --resume

Select one of the duplicate sessions with the name from the error.
Press x to delete it. Delete only one duplicate, not every session with that name.
Exit Copilot with Ctrl+C.
Run the Forge command again.
Alternatively, start a fresh session with the new naming format:

bash

frg code create --clear

Agent cannot resume the previous session

The agent reports an error such as session expired, session not found, or cannot resume session.

Cause

The session ID that Forge saved is no longer valid on the agent side, for example after the agent was reinstalled or the session was deleted.

Solution

Run the command again. Forge clears the stale session after this error, so the next run starts a fresh session.
To start fresh immediately, use --clear:

bash

frg issue plan --clear

Model behaviour

The agent ignores instructions or results vary a lot

Cause

The model selected by your profile or --model does not follow Forge's instructions reliably, for example a very new model.

Solution

Check the current model:

bash

frg config show

Switch to the stable profile, which is the default:

bash

frg config init --agent github_copilot --models stable --force

Or try another model for one run with --model <MODEL>.

See AI Model Selection for the models in each profile.