Common Issues and Solutions

Updated on Oct 5, 2026

Start here when a Forge command fails or does not do what you expect. This page shows you how to triage a problem in four steps, find your symptom, and collect diagnostics for a bug report. The sub-pages hold the detailed fixes.

Start here

Work through these steps in order. Most problems are solved by step 1 or 2.

text

 ┌──────────────────────────────────────────────────────────────────────────┐
 │ 1. frg status --verbose │
 │ Is Forge initialized? Is the agent installed and authenticated? │
 │ Is toolchain.toml present? │
 └───────────────┬──────────────────────────────────────────────────────────┘
 │ a check shows ✗ or ⚠ ──► follow the "Run:" hint it prints
 │ all checks pass, the problem remains
 ▼
 ┌──────────────────────────────────────────────────────────────────────────┐
 │ 2. frg diagnose │
 │ Offline readiness assessment: PASS / WARN / FAIL per check, │
 │ with a suggested next step for each failure │
 └───────────────┬──────────────────────────────────────────────────────────┘
 │ readiness is OK, but a workflow run fails
 ▼
 ┌──────────────────────────────────────────────────────────────────────────┐
 │ 3. Check logs and traces │
 │ .forge/work/<job>/traces/*.trace.md prompt, agent output, stderr │
 │ .forge/work/<job>/logs/system.log Forge's own log for the job │
 │ RUST_LOG=debug frg <command> more detail on the terminal │
 └───────────────┬──────────────────────────────────────────────────────────┘
 │ you now have the exact error message
 ▼
 ┌──────────────────────────────────────────────────────────────────────────┐
 │ 4. Find your symptom in the table below and open the linked section │
 │ Still stuck? Collect a support bundle and file a bug │
 └──────────────────────────────────────────────────────────────────────────┘

What steps 1 and 2 look like

frg status checks the project root, Forge initialization, the coding agent, and the toolchain. Each problem comes with the command that fixes it.

Example output in a repository where Forge is not set up yet (abbreviated):

text

Forge Status Check
=================

ℹ Project Root: /home/user/my-repo
⚠ Forge: Not initialized
 Run: frg config init

ℹ Coding Agent: not installed
 Error: Agent error: GitHub Copilot CLI is not installed or not found in PATH.
✗ Toolchain: Missing (REQUIRED)

 Run: frg config init --agent <agent> --issues <name> --code <name>
 Example: frg config init --agent github_copilot --issues github_issues --code github

frg diagnose runs the same kind of checks offline and summarizes readiness:

text

Forge Readiness Assessment
------------------------
✗ Status: Error
 Based on local configuration and diagnostic data.

Status Checks
-------------
 WARN Initialization: Project root found at . but .forge/ missing
 → Run 'frg config init' to initialize frg in this repository
 FAIL Agent: Agent not installed: GitHub Copilot CLI
 → Install GitHub Copilot CLI to use frg with AI agents
 FAIL Toolchain: toolchain.toml is missing (REQUIRED)
 → Run 'frg config init --issues <tool> --code <tool>' to create toolchain.toml

Find your symptom

Search this page for the text of your error (Ctrl+F). Messages are shown as Forge prints them; <n> and <name> stand for values that vary.

Installation and setup

Symptom or exact error	Likely cause	Go to
`frg: command not found` or `'frg' is not recognized`	The binary is not on `PATH`	Installation
`version 'GLIBC_2.39' not found`	Standard Linux binary on an older glibc	Installation
`Detected a musl-based system (e.g. Alpine Linux).`	Installer on Alpine or a host without detectable glibc	Installation
SmartScreen, AppLocker, or WDAC blocks `frg.exe`	Downloaded-file mark or organization policy	Installation
`Initial configuration required.`	No Forge configuration found for this directory	Configuration
`Toolchain: Missing (REQUIRED)`	`toolchain.toml` was never created	Configuration
`At least one of issue_tracker or ticket_tracker must be configured`	`toolchain.toml` has no tracker	Configuration
`Monorepo is enabled but no services are defined.`	`monorepo.enabled = true` without services	Configuration
`TOML parse error at line <n>, column <m>`	Syntax error in a configuration or workflow file	Configuration
`Configuration has changed since last lock.`	A config file changed after `frg config lock`	Configuration
`Telerik license not found.`	No license file or license variable	Configuration
`License expired on <date>` or `Your license is no longer valid.`	Expired subscription or trial	Configuration
`License signature verification failed`	License file edited or incomplete	Configuration
`Invalid OpenSearch URI format in telemetry.toml`	Bad `[opensearch]` settings	Configuration

Agents and sessions

Symptom or exact error	Likely cause	Go to
`GitHub Copilot CLI is not installed or not found in PATH.`	Agent CLI missing or not on `PATH`	Agent
`Install with: gh extension install github/gh-copilot` (from `frg config validate`)	Outdated install hint	Agent
`GitHub Copilot CLI is not authenticated.`	Agent not logged in	Agent
`Authentication check timed out - assuming authenticated (agent may be slow)`	Slow agent start-up	Agent
`No default agent is configured`	`agents.toml` missing or has no default	Agent
`command is not supported for GitHub Copilot invocation`	`command = "gh"` in `agents.toml`	Agent
`Agent exited with code <n>`	The agent CLI failed	Agent
Agent run times out	Large context, slow service, or rate limit	Agent
Claude Code stops mid-run on Windows	Agent process crashed	Agent
`Multiple sessions exist with name '<name>'`	A cancelled run left a duplicate Copilot session	Agent
`session expired` or `cannot resume session`	The agent no longer has the saved session	Agent
Run pauses and retries on its own	Transient upstream failure (HTTP 429, 5xx, timeout)	Runtime

Workflows

Symptom or exact error	Likely cause	Go to
`Issue ID required for 'issue' operations`	No issue, PR, or ticket context set	Workflow
`The --retry flag requires a previous session to continue.`	No session to continue	Workflow
`<n> output(s) missing`	Agent did not create every expected file	Workflow
`Prompt injection detected and BLOCKED`	Input matched a prompt-safety rule	Runtime
`Workflow lock held by PID <pid>`	Another workflow runs, or an interrupted run left a lock	Workflow
`Loop detection triggered, requesting approval`	A state was visited too many times	Workflow
`No step for non-terminal state`	A state has no command, operation, or approval	Workflow
`No terminal state is reachable from initial state`	Workflow definition never ends	Workflow

Tail, telemetry, and commands

Symptom or exact error	Likely cause	Go to
`No job context available for tail command`	`--tail` without an issue or ticket context	Tail
`Trace directory not found: <path>`	No workflow has run for this job yet	Tail
`Timeout waiting for trace file`	The workflow did not start	Tail
`OTLP authentication failed`	Wrong or missing endpoint headers	Runtime
`OTEL upload skipped - circuit breaker open`	Repeated upload failures	Runtime
`error: unrecognized subcommand 'telemetry'`	The command is not in your Forge version	Runtime
`A newer version of frg is available`	Update check notice	Runtime
`CI environment detected, exiting`	Beta terms not accepted in CI	Runtime
`Configuration not available for workflow execution.`	Internal configuration error	Configuration

Collect diagnostics

frg diagnose checks readiness offline and can package everything support needs into one archive. Use it instead of collecting system information by hand.

Option	Description	Default
`--format <FORMAT>`	Output format: `human` or `json`	`human`
`--bundle`	Generate a support bundle archive (`.tar.gz`)	Off
`-o, --output <PATH>`	Output path for the bundle	Timestamped file in the current directory
`--include-traces`	Include trace files from the last 24 hours	Off
`--include-logs`	Include log files from the last 24 hours	Off
`-v, --verbose`	Include detailed file paths and timing information	Off
`-q, --quiet`	Suppress all output except errors	Off

Common commands:

bash

# Readiness check in the terminal
frg diagnose

# Machine-readable output, for example to attach to a CI log
frg diagnose --format json

# Support bundle with recent logs and traces
frg diagnose --bundle --include-logs --include-traces --output frg-support.tar.gz

The bundle contains diagnostic.json, manifest.json, and the selected log and trace files. Forge does not overwrite an existing file. If the output path exists, the command fails with Output file already exists: <path>. Use --output to specify a different path.

Warning: Traces contain your prompts, agent output, and repository content. Open the bundle and remove anything confidential before you share it.

For JSON fields, size limits, and exit codes, see Diagnostic Command.

Logs and traces

Every workflow run writes to a job directory under .forge/work/. For issue-based work the directory is usually job_<issue_id>, for example .forge/work/job_42/.

Location	Contents
`.forge/work/<job>/traces/*.trace.md`	One timestamped file per agent run: context files, final prompt sent to the agent, agent output, and agent stderr
`.forge/work/<job>/logs/system.log`	Forge's internal log for the job, including OpenSearch and telemetry warnings
`.forge/work/<job>/logs/transaction.jsonl`	Machine-readable workflow events. See Transaction Logs
`.forge/work/ask/traces/`, `.forge/work/run/traces/`	Traces from `frg ask` and `frg run`, which do not use a job context
`.forge/logs/utility.jsonl`	Events from utility commands such as `frg config set-issue`

Find and read the most recent trace for issue 42:

bash

ls -t .forge/work/job_42/traces/ | head -n 5
less ".forge/work/job_42/traces/$(ls -t .forge/work/job_42/traces/ | head -n 1)"

Search the job logs for errors:

bash

grep -rn -i "error" .forge/work/job_42/logs/

To watch a trace while the agent runs, use frg --tail in a second terminal. See Tail Issues.

Turn on debug logging

Set RUST_LOG=debug to print detailed log output for one command:

bash

RUST_LOG=debug frg issue draft 2>&1 | tee frg-debug.log

In Windows PowerShell:

powershell

$env:RUST_LOG="debug"; frg issue draft 2>&1 | Tee-Object -FilePath frg-debug.log

Use RUST_LOG=trace only when support asks for it. It is very verbose.

Get help and report a bug

Search this guide. Run frg guide to open the user guide, or go to https://www.telerik.com/forge/documentation.
Check existing issues at https://github.com/telerik/forge/issues.
If the problem is new, open an issue there and include:

The output of frg --version and your operating system.
The agent you use (claude_code, github_copilot, or opencode) and its version, for example copilot --version.
The exact command you ran, with secrets removed.
The complete error message.
A support bundle from frg diagnose --bundle --include-logs --include-traces, after you remove confidential content.

For license purchases or renewals, contact your Progress representative.