Runtime Troubleshooting

Updated on Oct 5, 2026

Fixes for problems that appear while Forge runs: retries, prompt-safety blocks, telemetry uploads, update notices, CI behaviour, and commands that do not exist in your version. For agent failures, see Agent Issues. For workflow state and context errors, see Workflow Issues.

Agent retries

Retrying transient agent operation

You see this line with RUST_LOG=debug. Without debug logging, the command pauses and then continues.

Cause

Forge retries agent calls that fail for transient reasons, such as HTTP 429, HTTP 5xx, network timeouts, or a degraded upstream service. It waits with exponential backoff between attempts. Permanent errors, such as a missing agent or failed authentication, are not retried and show Retry skipped for non-retryable or exhausted agent error in the debug log.

Solution

1. Let the retry finish. Most transient failures clear on the next attempt.
2. If all attempts fail, check the agent provider's status page and try again later.
3. Tune retries with environment variables:

Variable	Description	Default
FORGE_RETRY_DISABLED	Set to true to turn off retries	Not set
FORGE_RETRY_MAX_ATTEMPTS	Retries after the first attempt. 0 turns off retries	2
FORGE_RETRY_INITIAL_DELAY	First delay in seconds	1
FORGE_RETRY_MAX_DELAY	Maximum delay in seconds	30
FORGE_RETRY_BACKOFF_FACTOR	Multiplier for each following delay	2.0

bash

FORGE_RETRY_MAX_ATTEMPTS=4 FORGE_RETRY_MAX_DELAY=60 frg issue plan

Verify

bash

RUST_LOG=debug frg issue plan 2>&1 | grep -i retry

Prompt safety

Prompt injection detected and BLOCKED

Cause

Your input, a context file, or an edit instruction matched a prompt-injection detection rule. Documentation about prompt injection, security training material, and code samples with shell commands are common false positives.

Solution

1. Check the flagged input and remove the matching text if it is not needed.
2. For a legitimate pattern that recurs, export the safety rules and add it to the allowlist:

bash

frg config export --security

Then edit .forge/config/.prompt-safety.toml. See Prompt Safety. 3. For a single run you have checked manually, bypass the check. Forge logs every bypass for audit:

bash

frg issue draft --bypass-safety-checks

Secret masking

A secret is visible in a trace file

Cause

The value does not match any built-in or custom secret pattern, so Forge did not redact it in .forge/work/<job>/traces/.

Solution

1. Delete or redact the affected trace file.
2. Rotate the exposed secret.
3. Add a custom pattern for the secret format. See Secret Masking.

Non-secret values are replaced with a redaction marker

Cause

A pattern is too broad and matches ordinary values.

Solution

1. Add the value or pattern to the allowlist, or narrow the custom pattern. See Secret Masking.

Telemetry and observability uploads

Telemetry is on by default. Upload failures never stop a workflow: Forge logs a warning and continues. Configuration errors in telemetry.toml are covered in Configuration Troubleshooting. For setup, see Progress and Observability.

OTLP authentication failed

Related messages: OTLP server error (<status>) and OTLP request failed: <reason>.

Cause

The OTLP collector rejected the request. Authentication headers in [endpoint.headers] are missing, expired, or wrong for this endpoint.

Solution

1. Find the telemetry.toml in use. FORGE_TELEMETRY_PATH overrides the search, which checks .forge/config/telemetry.toml, ~/.config/forge/telemetry.toml, and /etc/forge/telemetry.toml.
2. Update the headers your collector expects:

toml

[endpoint]
url = "https://otel.example.com:4318"
protocol = "http"

[endpoint.headers]
Authorization = "Bearer <token>"

3. Run a command and check the job's logs/system.log for new OTLP warnings.

Uploads skipped: 'circuit breaker open'

Messages: OTEL upload skipped - circuit breaker open, OpenSearch upload skipped - circuit breaker open, Trace upload skipped - circuit breaker open.

Cause

After repeated upload failures, Forge opens a circuit breaker and skips uploads immediately so that workflows are not slowed down. It tests the connection again later and resumes uploads when the endpoint responds (Circuit breaker closed - OpenSearch connection restored).

Solution

1. Look for the first failure in .forge/work/<job>/logs/system.log. It names the real cause, for example authentication or a certificate error.
2. Fix that cause: endpoint URL, token, network access, or certificates. For self-signed OpenSearch certificates on a trusted network, set accept_invalid_certs = true in [opensearch].
3. Run another command. Uploads resume after the breaker closes.

Turn off telemetry

Cause

You do not want to send usage data, or uploads fail in an isolated environment.

Solution

1. Turn off telemetry for one shell:

bash

export FORGE_TELEMETRY_DISABLED=1

2. Or turn off usage analytics in telemetry.toml:

toml

[usage]
enabled = false

Commands and flags

error: unrecognized subcommand

For example error: unrecognized subcommand 'telemetry'.

Cause

The command does not exist. The name may be misspelled, or the page you followed may describe a command that was renamed.

Solution

1. Check the commands your installation supports:

bash

frg --version
frg --help

2. Use the supported equivalent:

You tried	Use instead
frg completions	frg shell install <shell> or frg shell generate <shell>
frg trace list, frg trace view	Read files in .forge/work/<job>/traces/, or stream with frg --tail
frg issues	frg issue (singular)

3. Get help for a specific command:

bash

frg issue --help

Update check

A newer version of frg is available

Cause

In interactive terminals Forge checks GitHub for a newer stable release and prints a notice. The check is skipped in CI and non-interactive environments. If the check itself fails you see Background update check failed:, which does not affect the command.

Solution

1. To upgrade, run the installer again. See the Installation Guide.
2. To turn off the check for a shell or a CI job:

bash

export FORGE_NO_UPDATE_CHECK=1

3. To turn it off in configuration, see Update Check.

CI and non-interactive environments

CI environment detected, exiting

Cause

Forge asks you to accept its beta terms the first time it runs. In CI it cannot prompt, so it exits.

Solution

1. Accept the beta terms with an environment variable in the CI job:

bash

export FORGE_ACCEPT_BETA_RISK=1

2. For frg app discover --auto, also set FORGE_ACCEPT_AUTO_RISK=true.
3. Make sure the agent is installed and authenticated on the runner. Run frg status as a pipeline step.

Verify

bash

frg status

See FORGE_ACCEPT_BETA_RISK in Environment Variables.

'frg guide' does not open the user guide

Cause

The machine has no default browser, for example a server or SSH session.

Solution

1. Open the published guide directly: https://www.telerik.com/forge/documentation.

See Also

• Common Issues and Solutions
• Environment Variables
• OpenSearch Integration
• Progress and Observability
• Prompt Safety