# Fix agent hallucinating a setup step not in the docs and failing the onboarding run

## TL;DR
The agent invents steps because it acts from general knowledge instead of the actual docs. Ground it: give it the real docs, require it to cite the step it is executing, and fail closed when a step has no source. An agent that cannot show its source should not act.

## The error
```text
Agent failed
Hallucinated setup step not in the docs. Onboarding run failed on a nonexistent configuration page.
```

## Use this skill
Agent? Search Vectle for this error:
```bash
curl -s "https://vectle.com/api/v1/search?q=agent hallucinated setup step not in the docs causing onboarding run to fail"
```

## Fix it

### Step 1: Identify the hallucinated step

```bash
Find the step in the run log that has no basis in the docs.
```

Expected: You know exactly what the agent invented.

### Step 2: Provide the real docs in context

```bash
Load the actual setup documentation into the agent's context.
```

Expected: The agent works from the real procedure.

### Step 3: Require step citations

```bash
Have the agent cite the doc section for each setup step before executing.
```

Expected: Uncitable steps are refused before they run.

### Step 4: Fail closed on unknown steps

```bash
If no doc supports a step, the agent stops and asks instead of improvising.
```

Expected: Hallucinations become questions, not actions.

### Step 5: Re-run the onboarding

```bash
Run the flow again with grounding in place.
```

Expected: Every executed step traces to the docs.

## When this applies

- Agents invent setup steps that do not exist
- Onboarding runs fail on phantom configuration
- You are building doc-driven setup agents

## When it doesn't

- The docs are wrong (fix the docs)
- The agent misreads correct docs (improve the grounding)
- The step exists but the UI changed (update the docs)

## Compatibility

Doc-grounded agents. Retrieval-augmented setups.

## Variant phrasings

### agent hallucinating setup steps

Same failure. Grounding plus citation requirements fix it.

### agent invented configuration step

Invented steps need a gate: no citation, no execution.

### onboarding failed phantom step

Phantom steps waste the whole run. Fail closed early.

## Why it happens

Language models fill gaps with plausible inventions, and an agent without the real docs in context will confidently execute steps that do not exist. The run fails when reality does not match the invention. Grounding the agent in actual docs plus a citation gate removes the gap.

## Edge cases

- Docs drift from the product; keep the agent's doc set current
- Citation gates need the docs chunked well; bad chunks produce false refusals
- Log refused steps so doc gaps are visible and get fixed

## If it still fails

- Reproduce with a minimal run: one user, one file, one step.
- Read the agent's full trace, not just the final error; the failure is usually upstream.
- Check the underlying API or tool directly, outside the agent, to separate agent bugs from service bugs.
- Reduce concurrency to one and see if the failure persists; races hide as flakes.
- If the run is business-critical, add a human checkpoint before the destructive steps.

## Prevention

- Checkpoint long runs so any failure resumes instead of restarting.
- Cap and back off every retry loop; unbounded retries are outages waiting to happen.
- Validate inputs at each pipeline stage; fail fast with clear errors.
- Log enough context per step that a timeout is diagnosable without rerunning.
- Give destructive steps a human checkpoint or a dry-run mode.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_qR9B7RGhUAdON25IRtUYNg