Knowledge Troubleshooting

Resolve indexing errors, ungrounded assistant answers, crawler timeouts, and document parsing bugs.

Overview

When assistant answers fail to reflect your documentation, use this guide to identify whether the issue lies in crawler access, vector indexing, similarity thresholds, or prompt constraints.

Assistant Gives Generic or Ungrounded Replies

Verify Source Index Status: In Knowledge > Sources, confirm the source shows status Ready. If it shows Processing or Error, re-index the source.

Check Collection Assignment: In Assistants > Knowledge, verify the collection containing your source is assigned to the active assistant.

Lower Similarity Threshold: In Knowledge Settings, test lowering the similarity threshold from 0.80 to 0.70.

Crawler Fails with 403 or Timeout

Cloudflare / WAF Block: Whitelist the Asiyst Crawler user-agent (AsiystBot).

Robots.txt: Ensure robots.txt allows crawling of your documentation path.

Document Upload Rejected

Confirm file size is under 50 MB.

For PDFs, verify that text is selectable (not flattened raster images without OCR).

Diagnostic Commands

# Test knowledge health via CLI

asiyst knowledge validate --project proj_9f8a2b3c4d

Docs/Knowledge Base

Knowledge Base