Skip to content

Knowledge Troubleshooting

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

View as Markdown Open the plain-text version of this page.

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.

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.

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#