Getting Started
Licensing
System Requirements
Troubleshooting / Configuration Troubleshooting
New to FORGE? Start a free 30-day trial

Configuration Troubleshooting

Updated on Oct 5, 2026

Fixes for errors from frg config commands and for configuration problems that stop workflow commands before the agent runs. Start with frg config validate and frg config show --verbose: they list every configuration file Forge found and whether it is valid.

Initialization

Initial configuration required.

Cause

Forge found no configuration for the current directory. You are outside the project, or you never ran frg config init here.

Solution

  1. Go to the repository root.
  2. Initialize Forge with an agent and a toolchain:
bash
frg config init --agent github_copilot --issues github_issues --code github

Verify

bash
frg status

Required configuration not found

text
Error: Configuration error: Required configuration not found

Searched for project.toml in:
 /path/to/dir/.forge/config/project.toml

Cause

The command needs project.toml, but the directory has none. This happens in an application root that only has application.toml, or in a directory outside the project.

Solution

  1. Check the searched path in the message. If it is the wrong directory, cd to the repository root.
  2. If this repository was never initialized, run:
bash
frg config init

Verify

bash
frg config show

Toolchain: Missing (REQUIRED)

frg config validate or a workflow command can also print toolchain.toml is required. Run 'frg config init --issues <name> --code <name>' to create it.

Cause

.forge/config/toolchain.toml does not exist. Workflow commands need it to know your issue tracker and code platform.

Solution

  1. Create it:
bash
frg config init --issues github_issues --code github
  1. If the file already exists and you want to replace it, add --force:
bash
frg config init --issues github_issues --code github --force

Verify

bash
frg status

frg status shows ✓ Toolchain: Configured.

At least one of issue_tracker or ticket_tracker must be configured

Cause

toolchain.toml exists but defines neither an issue tracker nor a ticket tracker.

Solution

  1. Regenerate the file with a tracker:
bash
# Issue tracker
frg config init --issues github_issues --code github --force

# Or a ticket tracker
frg config init --tickets jira --code github --force
  1. Alternatively, edit .forge/config/toolchain.toml by hand. See Toolchain Configuration.

Verify

bash
frg config validate
frg config show

Monorepo is enabled but no services are defined

Full message: Monorepo is enabled but no services are defined. Add [[monorepo.services]] entries or set monorepo.enabled = false.

Cause

project.toml sets monorepo.enabled = true but has no [[monorepo.services]] entries.

Solution

  1. Add a [[monorepo.services]] entry for each service. See Monorepo.
  2. Or, if the repository is not a monorepo, set enabled = false in the [monorepo] section.

Verify

bash
frg config validate

agents.toml already exists

The same happens for toolchain.toml already exists and project.toml already exists.

Cause

frg config init does not overwrite existing configuration files by default.

Solution

  1. Pass the option that selects the file together with --force:
bash
# Replace agents.toml
frg config init --agent claude_code --force

# Replace toolchain.toml
frg config init --issues jira --code github --force

# Edit project.toml interactively
frg config init --interactive --force
  1. --force alone fails with --force requires at least one configuration option. It cannot be combined with --app.

Verify

bash
frg config show

Validation

TOML parse error at line <n>, column <m>

Example from frg config validate:

text
Error: Workflow schema error: Invalid TOML in '.forge/config/workflows/hello-workflow.toml': TOML parse error at line 3, column 1
 |
3 | [workflow]
 | ^^^^^^^^^^

Cause

A configuration or workflow file has a TOML syntax error: an unclosed quote, a duplicate table, or a missing =.

Solution

  1. Open the file named in the message and go to the line and column shown.
  2. Fix the syntax.
  3. Validate only that file:
bash
frg config validate --file .forge/config/commands.toml
  1. For a workflow file, use the focused validator:
bash
frg workflow validate hello-workflow

Verify

frg config validate ends with ✓ All configuration files are valid.

Configuration lock

The lock is opt-in. frg config lock validates all configuration files and writes .forge/.config_lock with a SHA-256 hash of each file. While the lock file exists, workflow commands refuse to run if any configuration file changes.

Configuration has changed since last lock.

Cause

A configuration file listed under Changed files: was edited after the lock was written.

Solution

  1. Review the changes, for example with git diff .forge/config/.
  2. If the changes are intended, validate and lock again:
bash
frg config lock
  1. If the changes are not intended, revert them.

Verify

Run the workflow command again.

Lock file is corrupted or invalid.

Cause

.forge/.config_lock was edited by hand or damaged, for example by a merge conflict.

Solution

  1. Regenerate the lock file:
bash
frg config lock
  1. To stop using the lock entirely, delete .forge/.config_lock.

Verify

frg config show shows the current Lock Status.

License

For license file names, locations, and discovery order, see Licensing.

Telerik license not found.

frg learn prints the same message followed by Workflow tutorials require a valid Telerik license.

Cause

Forge found no license file in any searched location and no license environment variable.

Solution

  1. Place telerik-license.txt in .forge/license/ at the project root, or in ~/.config/forge/license/.
  2. Or set the license content or path in an environment variable:
bash
export TELERIK_LICENSE_PATH="/secure/location/telerik-license.txt"

Verify

Run the command again. If the license is still not found, Forge lists every location it searched.

License expired on <date>

Related message: Your license is no longer valid.

Cause

The subscription or trial license is past its expiration date.

Solution

  1. Contact your Progress representative to renew.
  2. Replace the old license file with the new one.

License signature verification failed

Related messages: The license file exists but has an invalid signature., The license file could not be parsed., and License file exceeds maximum size of <n> bytes.

Cause

The license file was edited, truncated, or saved with extra content. Any change breaks the signature.

Solution

  1. Download the original license file again. Do not open it in an editor that changes line endings or encoding.
  2. Replace the existing file.

Telemetry and OpenSearch settings

Telemetry, OTLP export, and OpenSearch are configured in telemetry.toml. See Progress and Observability and OpenSearch Integration. Upload failures during a run are covered in Runtime Troubleshooting.

Invalid OpenSearch URI format in telemetry.toml

Related message: OpenSearch API token is empty in telemetry.toml. In both cases Forge disables OpenSearch uploads and continues.

Cause

The [opensearch] section has a malformed uri or an empty api_token.

Solution

  1. Find the file in use. Forge checks FORGE_TELEMETRY_PATH, then .forge/config/telemetry.toml, then ~/.config/forge/telemetry.toml, then /etc/forge/telemetry.toml.
  2. Fix the section:
toml
[opensearch]
uri = "https://opensearch.example.com:9200"
api_token = "<token>"

Verify

Run a workflow and check .forge/work/<job>/logs/system.log for OpenSearch warnings.

OTEL endpoint must start with http://, https://, or grpc://

Related messages: OTEL timeout_secs must be between 1 and 60 and OTEL endpoint uses HTTP instead of HTTPS - this is a security risk.

Cause

The [endpoint] section of telemetry.toml has an invalid url or timeout_secs, or uses plain HTTP.

Solution

  1. Correct the endpoint:
toml
[endpoint]
url = "https://otel.example.com:4318"
protocol = "http"
timeout_secs = 10
  1. Use https:// outside local testing.

Export

not found in built-in workflows

Cause

frg config export --target <TARGET> received a target name that has no built-in workflow.

Solution

  1. Use a workflow target such as issue, backlog, code, pr, docs, ticket, or sec:
bash
frg config export --prompts --target issue
  1. Remember that you must also choose what to export: --commands, --prompts, --workflows, --skills, --security, or --all.

Export does not overwrite existing files

Cause

frg config export keeps files you have already customized.

Solution

  1. Back up the existing files:
bash
cp -r .forge/prompts .forge/prompts.bak
  1. Export again with --force:
bash
frg config export --prompts --target issue --force

Internal errors

Configuration not available for workflow execution.

Cause

This is an internal error: Forge discovered the configuration at start-up, but the workflow handler did not receive it. The most common trigger is running a workflow command in a directory that is not initialized.

Solution

  1. Confirm that you are in the project root and that it is initialized:
bash
frg status
frg config validate
  1. If .forge/config/project.toml is missing, run frg config init.
  2. If the project is configured correctly and the error persists, report it. The message links to https://github.com/Progress-Copilot/frg/issues, which is a private repository. Use https://github.com/telerik/forge/issues instead and include the Debug information block and the command you ran.

Automatic configuration (frg app discover --auto)

frg app discover --auto uses AI analysis to create project.toml for child repositories that do not have one.

Existing repositories are skipped

Cause

This is expected. --auto never overwrites an existing project.toml.

Solution

  1. To correct one repository, run frg config init --interactive --force in that repository.
  2. To regenerate it from scratch, back up and delete its .forge/config/project.toml, then run frg app discover --auto again.

Generated configuration has wrong values

Cause

AI analysis can misidentify the framework, test framework, or package manager, especially in repositories with several toolchains.

Solution

  1. Review and correct each field with AI suggestions:
bash
frg config init --interactive --force
  1. Or edit .forge/config/project.toml directly and run frg config validate.

--auto stops in CI or a non-interactive shell

Cause

Before it runs, --auto shows a warning about AI-generated content that needs confirmation.

Solution

  1. Confirm the risk with the environment variable:
bash
FORGE_ACCEPT_AUTO_RISK=true frg app discover --auto
  1. Review the generated project.toml files before you commit them.

No child repositories are found

Cause

frg app discover only finds repositories whose project.toml has an allow_app value matching the application UUID in application.toml.

Solution

  1. Check the application UUID:
bash
cat .forge/config/application.toml
  1. Add allow_app = "<application-uuid>" to each child repository's project.toml.
  2. Run discovery again:
bash
frg app discover

See Also

In this article
InitializationInitial configuration required.Required configuration not foundToolchain: Missing (REQUIRED)At least one of issue_tracker or ticket_tracker must be configuredMonorepo is enabled but no services are definedagents.toml already existsValidationTOML parse error at line <n>, column <m>Configuration lockConfiguration has changed since last lock.Lock file is corrupted or invalid.LicenseTelerik license not found.License expired on <date>License signature verification failedTelemetry and OpenSearch settingsInvalid OpenSearch URI format in telemetry.tomlOTEL endpoint must start with http://, https://, or grpc://Exportnot found in built-in workflowsExport does not overwrite existing filesInternal errorsConfiguration not available for workflow execution.Automatic configuration ( frg app discover --auto )Existing repositories are skippedGenerated configuration has wrong values--auto stops in CI or a non-interactive shellNo child repositories are foundSee Also