Workflow Issues

Updated on Oct 5, 2026

Fixes for workflow commands (frg issue, frg code, frg pr, and so on) and for stateful workflows run with frg workflow. For agent installation and login problems, see Agent Issues.

Context

Issue ID required for 'issue' operations

Full message:

text

Issue ID required for 'issue' operations
Set the Issue ID using one of these methods:
1. Environment variable: export FORGE_ISSUE_ID=<number>
2. Config file: frg config set-issue <number>
Current context: frg config show-context

Similar messages exist for other targets: Issue ID required for 'code' operations, Issue ID required for 'docs' operations, Pull Request ID required for 'pr' operations, and Ticket ID required for 'ticket' operations.

Cause

The command works on a specific issue, pull request, or ticket, and no ID is set.

Solution

Set the ID for the current shell:

bash

export FORGE_ISSUE_ID=42

Or save it in the project context file, .forge/context.toml:

bash

frg config set-issue 42 # also accepts tracker IDs such as PROJ-456 or AB#789
frg config set-pr 128
frg config set-ticket 123456

Run the command again.

Verify

bash

frg config show-context

Context is set but Forge uses a different ID

Cause

An environment variable overrides the context file. frg config clear-context removes the IDs from .forge/context.toml but does not unset FORGE_ISSUE_ID or FORGE_PR_ID.

Solution

Check the source of each value:

bash

frg config show-context

Unset stale environment variables:

bash

unset FORGE_ISSUE_ID FORGE_PR_ID FORGE_TICKET_ID

Set the ID you want with frg config set-issue <id>.

Invalid pr_id '0': must be a positive integer

Cause

A pull request ID must be 1 or greater.

Solution

Set a valid PR number:

bash

frg config set-pr 128

If the value comes from the environment, fix or unset FORGE_PR_ID.

Outputs and retries

Expected outputs are missing

With --auto-retry you see <n> output(s) missing, retrying with completion prompt....

Cause

AI agents are non-deterministic and do not always create every file the command expects.

Solution

Continue the same session with a prompt that lists the missing files:

bash

frg code create --retry

Add your own instructions:

bash

frg issue plan --retry "The phase_3.md file needs a testing strategy"

Retry automatically once on the next run, for example in CI:

bash

frg code create --auto-retry

--retry and --auto-retry need the existing session, so you cannot combine them with --clear. See Modifiers.

The --retry flag requires a previous session to continue.

Cause

There is no saved session for this command to continue. The command never ran in this context, the session was cleared with --clear, or the context ID changed.

Solution

Check that the context is the same as in the original run:

bash

frg config show-context

Run the command without --retry to create a session:

bash

frg code create

Use --retry afterwards if outputs are missing.

Command finishes without visible output

Cause

The command ran with -q/--quiet, the agent wrote its results only to files, or the run failed quietly before the agent started.

Solution

Run again without --quiet.
Look at the job directory for created files and traces:

bash

ls -lt .forge/work/job_42/ .forge/work/job_42/traces/

See the prompt Forge would send, without running the agent:

bash

frg issue draft --print-prompt

Run with debug logging:

bash

RUST_LOG=debug frg issue draft

Prompt not found

Cause

A prompt override or customized workflow refers to a prompt file that does not exist.

Solution

Export the built-in prompts for the target as a starting point:

bash

frg config export --prompts --target issue

Compare the file names under .forge/prompts/ with the names your configuration uses.
For prompt override declarations, see the AI Coding Agent Troubleshooting Guide.

Workflow lock

Only one stateful workflow can run in a repository at a time. Forge records the running workflow in a lock file.

Workflow lock held by PID

Full message: Workflow lock held by PID <pid> (started at <time>) for <workflow> on <host>.

Cause

Another workflow is running in this repository, or an earlier run was interrupted (Ctrl+C or a crash) and left the lock behind. If the process in the lock no longer exists, Forge normally overrides the stale lock by itself.

Solution

Check whether a workflow is still running:

bash

frg workflow status

If it is running, wait for it to finish, or stop it in its terminal.
If nothing is running, release the lock:

bash

frg workflow unlock

Forge prints Stale workflow lock released. 4. If Forge still considers the lock valid and you are sure no workflow runs, force it:

bash

frg workflow unlock --force

To run workflows in parallel, use separate git worktrees or repository folders.

Verify

bash

frg workflow unlock

Forge prints No workflow lock found in this repository.

Workflow definitions

Validate a definition before running it. frg workflow validate needs no issue or PR context.

bash

frg workflow validate my-workflow
frg workflow graph my-workflow --print
frg workflow run my-workflow --dry-run

For the schema, see Workflow Schema.

No terminal state is reachable from initial state

Related message: Workflow must define terminal_states with at least one success or failed state.

Cause

No chain of transitions leads from the initial state to a success or failed terminal state, so the workflow could never end.

Solution

Draw the workflow to see the transitions:

bash

frg workflow graph my-workflow --print

Add the missing success and failure transitions so that every path reaches a terminal state.
Validate again:

bash

frg workflow validate my-workflow

State is unreachable from initial state

text

State '<name>' is unreachable from initial state '<initial>'

Cause

A state is defined, but no transition leads to it. This is a warning; the workflow can still run.

Solution

Remove the unused state, or add a transition to it from another state.
Validate again with frg workflow validate <name>.

Non-terminal states must have command, operation, operations, or approval

At run time the same problem is logged as No step for non-terminal state.

Cause

A state that is not terminal has nothing to execute, so the workflow cannot move on.

Solution

Give the state a command, operation, operations, or approval, or make it a terminal state.
Check state names and types:

bash

frg workflow run my-workflow --list-states

Validate again with frg workflow validate my-workflow.

Invalid escape condition in state

Related messages: Escape condition with action 'transition' requires 'target_state' and Escape condition with action 'approval' requires 'approval_gate'.

Cause

A loop escape condition is incomplete.

Solution

Add the field that the action needs: target_state for transition, approval_gate for approval.
Validate again. See Loops and Retries.

Running workflows

Loop detection triggered, requesting approval

You may also see Loop Detection: Approval required for state '<name>', '<state>' visited <n> times (limit: <limit>) - circular workflow detected, or Maximum transitions (<n>) exceeded - possible circular workflow.

Cause

A state was visited more often than its limit, which usually means the workflow is stuck in a loop, for example a review that keeps failing. Forge pauses and asks for approval before it continues.

Solution

Inspect the workflow and its artifacts:

bash

frg workflow status my-workflow --verbose

If another iteration is useful, approve it. Use the workflow ID and code that Forge printed:

bash

frg workflow approve --workflow-id <id> --code <code> --email <email>

If the loop will not converge, reject the approval and fix the cause:

bash

frg workflow reject --help

Adjust visit limits or escape conditions in the workflow definition.

Workflow was interrupted or failed mid-run

You see Workflow interrupted by user (Ctrl+C) or Workflow failed.

Solution

List the states to find where to continue:

bash

frg workflow run my-workflow --list-states

Continue from that state:

bash

frg workflow run my-workflow --start-from <state-name>

If the run reports a held lock, see Workflow lock held by PID.

Shell step timed out

Related message: Command timed out after <n> seconds.

Cause

A shell or command step ran longer than its timeout.

Solution

Run the command from the step by hand to see how long it takes and whether it waits for input.
Make the command non-interactive, or raise the step timeout in the workflow definition. See Workflow Steps.

Job directory not found

Full message ends with Use 'frg workflow status' without --work-dir to see available jobs.

Cause

frg workflow status --work-dir <WORK_DIR> points to a job directory that does not exist under .forge/work/.

Solution

List the jobs Forge can find:

bash

frg workflow status

Use one of the listed directories, for example:

bash

frg workflow status --work-dir job_20260713_120000_5678