# Knowledge Troubleshooting

## No items are being extracted

### Check that extraction is enabled

In the Workbench **Knowledge** page, confirm automatic extraction is on. With the CLI:

```bash
provon knowledge settings get
```

If extraction is disabled, automatic runs and backfills are skipped.

### Check that at least one goal is active

Only `active` goals participate in extraction. Paused or archived goals are ignored.

```bash
provon knowledge goals list --status active
```

### Check that the conversation exists and is inactive

Extraction runs after a conversation has been inactive for about 10 minutes. Very recent traces are
not candidates yet. Newer activity for the same conversation supersedes an older snapshot.

### Check that the goal has a non-empty instruction

A goal with no instruction produces no items. Verify the instruction in the Workbench or with:

```bash
provon knowledge goals get <goal-id>
```

### Check that a model provider is configured

If the runtime cannot call an extraction model, candidates cannot be produced. The job is skipped
with reason `extractor_unavailable`. Configure a Gateway model provider or project default model.

## Backfill returns an error

| Error                 | Cause                                            | Fix                                                  |
| --------------------- | ------------------------------------------------ | ---------------------------------------------------- |
| `invalid_window`      | `startMs >=` `endMs` or non-finite values        | Provide a valid time window where `startMs < endMs`. |
| `invalid_budget`      | `maxConversations` out of range                  | Use an integer between 1 and 100,000.                |
| `goal_not_found`      | Goal ID does not exist or is not in this project | Check the goal ID.                                   |
| `goal_inactive`       | Goal is `paused` or `archived`                   | Activate the goal before backfilling.                |
| `extraction_disabled` | Project extraction setting is off                | Enable extraction first.                             |

Backfills are asynchronous. A `202 Accepted` response means the job was scheduled, not that items
were produced. Polling may be required.

## Backfill produced no items

- The time window may not contain any conversations.
- The conversations may not match the goal's instruction.
- The extraction model may have returned no candidates (`no_knowledge_candidate`).
- The trajectory may be missing for those conversations (`trajectory_missing`).

Try broadening the time window or refining the goal instruction. See [Knowledge best
practices](./best-practices.md).

## Items are low quality or inconsistent

1. Make the goal instruction more specific. State what to capture and what to ignore.
2. Split broad goals into narrower ones.
3. Review low-confidence items and archive unsupported ones.
4. Pause the goal while iterating, then run a small backfill to validate the new instruction.

## Duplicate items appear

Knowledge uses the goal ID, normalized title, and normalized content to derive a stable item ID.
Identical candidates from different conversations update the same item rather than creating a
duplicate. If you see what looks like duplicates, the normalized content likely differs slightly.
Edit or archive the redundant item.

## Items are missing evidence links

Each item stores `evidenceRefs` that reference the source conversation. If the conversation or the
trajectory was deleted or never materialized, the evidence link may be unresolvable. Ensure traces
are retained according to the project's telemetry retention policy.

## CLI `find` returns no matches

`provon knowledge find` requires every normalized search term to appear in the item title, content,
or Learning Goal name. Check that:

- the local snapshot is current (`provon knowledge pull`);
- the search terms are not overly specific;
- the items you expect are `active` (the CLI only searches active items).

## Cannot update an item status

Valid item statuses are `active` and `archived`. If you are using the API or CLI, check that the
status value is one of these two.

## See also

- [Knowledge quickstart](./quickstart.md) — first extraction flow.
- [Knowledge best practices](./best-practices.md) — improve goal quality.
- [Knowledge API](../api/knowledge.md) — backfill and item endpoint details.
- [Knowledge CLI](../cli/knowledge.md) — local snapshot and search commands.