Troubleshooting & FAQ

The most common issues, fixes, and questions, organized by symptom.

Workflows

A workflow is taking longer than expected

Typical workflows run 90–180 seconds. If yours is taking noticeably longer:

The agent is probably on a refinement loop. Watch the chat panel — it streams progress and will show which loop it's on. The hard cap is 3 loops, so the workflow will terminate.
For very large selections, more content has to be processed. Try narrower selection on the next run.
If the workflow appears genuinely stuck (no streaming progress for over a minute), refresh the page. Partially-applied edits are committed; anything in-flight rolls back.

The agent says it can't find what I asked about

That's a KB limitation — the system telling you the answer isn't in your corpus, instead of inventing one. Options:

Add relevant papers to the KB (most often the right move).
Relax the question.
Accept the gap and frame your work around it.

See Confidence, Gaps & Iteration Limits.

Workflow finished but the mindmap didn't change

Two possibilities:

The agent took the direct answer route — your question was answerable from the existing map, no edits needed. The chat panel will have the answer.
The workflow failed to find anything useful and produced only a summary. Check the summary for limitations and follow-up suggestions.

"That's not what I asked for"

Three failure modes, with different fixes:

Scope wrong. Selection was too wide or too narrow. Fix selection and re-issue. See Agent Context.
Instruction routed the wrong way. You asked for an edit and got research (or vice versa). Re-phrase using verbs from the Writing Instructions routing patterns.
Result drifted from intent. Refine in conversation rather than re-issuing — "That's too broad. Narrow to X." See Conversational Refinement.

Citations and claims

A citation points to a passage that doesn't seem to support the claim

This happens occasionally with low-confidence claims. Steps:

Open the node and check the confidence score.
Open the citation in the PDF reader and read the surrounding paragraph.
If the passage genuinely doesn't support the claim, edit or delete the claim. Use version history for context on when the node was created.

If you find a pattern of unsupported citations, that's a signal to either tighten your instructions (more "use only what the KB directly states") or check whether your KB has indexing problems on those documents.

Confidence scores look unusually low across a branch

Usually a sign of one of:

The branch is on contested ground (the scoring is doing its job).
The KB is thin on this specific topic — coverage limitation.
The instruction was too broad and the agent stretched to fill it.

Inspect a few low-confidence nodes' citations to figure out which case applies.

Knowledge bases

A PDF won't index — stuck in "Failed"

Most common causes:

Corrupted or password-protected PDF. Re-download or unlock the original.
OCR failure on a scanned PDF with poor image quality. There's no automatic re-OCR — your best move is to find a better-quality version of the document, or use external OCR before uploading.
Quota / credit issue. Indexing consumes credits. If your balance is too low, indexing fails — see Credits & Billing.

Remove the failed file and try again with a fixed version. Failed files don't auto-retry.

Indexing is slow

Indexing time scales with document length and PDF complexity. A 30-page paper is typically a couple of minutes. A 400-page book can be 15–30 minutes. The KB detail page polls every 10 seconds while files are processing — you don't need to refresh manually.

A document is missing from the project's results even though it's in a KB

Check that the KB is actually attached to the current project (Manage Knowledge Bases on the project page). The KB list and the project's attached-KB list are separate — uploading to a KB doesn't auto-attach it to any project.

Zotero plugin

Panel doesn't appear in Zotero

Confirm the selected item is a regular library item, not a note, attachment, or saved search.
Open Tools → Plugins and verify Agent Bayes is enabled.
Restart Zotero.

"Invalid API key" in Zotero

Open Settings → API Keys in the web app.
Confirm the key is still active. If not, create a new one and update Zotero's preferences pane.
In Zotero's preferences pane, click Test Connection to verify.

If the key looks correct but the test still fails, it's a network issue between Zotero and the backend. Check that your machine can reach app.agentbayes.com.

Sync issues badge keeps appearing

The plugin audits server documents against your local Zotero library on startup. Two kinds of issues surface:

Metadata diverged — local and server disagree on title, authors, or year. Open the Sync Issues dialog and resolve each per-item or in bulk.
Orphaned on server — a server document references a Zotero item that no longer exists locally. Choose Delete from Server (permanent) or Disassociate (keeps the document, unlinks it from Zotero).

Acknowledged issues stay dismissed unless either side changes again.

Credits and billing

Balance dropped unexpectedly during a workflow

Workflows reserve the estimated cost up-front and release the reservation when the workflow completes. Your visible balance briefly dips by the reservation amount and then partly recovers when the actual usage is recorded. The history view (Settings → Credits) shows reservations and usage as separate entries.

Include the project name (and ideally a link).
Describe what you expected vs. what happened.
For workflow issues, paste the workflow summary text — it has all the diagnostic context.

What's next

Settings & API Keys — managing keys and integrations.
Confidence, Gaps & Iteration Limits — understanding what the agent reports.