Troubleshooting

Start with the layer that failed

Most Calypso RAG issues become easier to solve when you identify the failing layer first:

• key and authorization
• knowledge readiness
• agent policy
• Playground validation
• integration wiring
• post-launch widget outcomes

Playground cannot send

Check:

• an active project API key exists
• the correct key is selected
• the selected key still belongs to the current project

The answer is weak or ungrounded

Check:

• whether the source is truly indexed
• whether the source pool is too broad or too weak
• whether the selected profile is the one you intended
• whether the answer returned sources, hid them, or never grounded at all

Upload succeeded but the source is not searchable

Check:

• whether the upload response says queued, accepted, or indexing instead of active
• for single-file uploads, poll GET /v1/knowledge/files/{file_id} or GET /v1/knowledge/tasks/{task_id}
• for batch uploads, poll GET /v1/knowledge/batches/{batch_id}?include_items=true
• whether the file has bucketSyncStatus: active when querying through a bucket
• whether the upload was a dry run, which validates but does not write files

An upload can be accepted before it is searchable. Accepted means Calypso stored the file and queued indexing work. Retrieval is ready only after indexing, and bucket-scoped retrieval is ready only after bucket sync becomes active.

Upload fails with bucket_required

Check:

• single-file uploads include one of bucket_ids, bucket_slugs, or bucket
• batch uploads include a shared bucket destination, or every item has its own bucket fields
• the UI has at least one active bucket available before uploading
• MCP calls to calypso-upload-knowledge-file or calypso-upload-knowledge-files-batch include bucketIds, bucketSlugs, or bucket

Durable knowledge uploads are bucket-backed. Calypso rejects uploads that do not specify where the file should land.

Upload fails with bucket_assignment_failed

Check:

• the bucket id exists in the selected workspace
• the bucket slug is spelled correctly
• create_missing_buckets=true is set when using a new slug that should be created
• the requested bucket is active and not archived

Fix the destination and retry with the same idempotency key only if the request body is otherwise identical.

Batch upload shows accepted but the bucket is empty

Check:

• the batch status counters: queued, indexing, active, and failed
• each item’s status and error details
• whether the files were assigned to the intended bucket, bucket_slugs, or bucket_ids
• whether the integration reused duplicate or unsafe client_file_id values
• whether the batch exceeded 100 files or hit the team rate limit

Bucket pages list active bucket members only. Queued or indexing files are visible through batch/file status first, then appear in the bucket after indexing and bucket sync complete.

A named profile is not behaving as expected

Check:

• the exact model ID being called
• whether the profile still exists
• whether the intended profile has different scope or presentation settings than the default agent

The widget is live but answers do not match Playground

Check:

• whether the widget is using linked-agent mode
• which agent is actually bound to the widget
• whether the default agent or a named profile was intended

Analytics are empty

Check:

• whether the selected team is correct
• whether the widget has enough activity for the selected range
• whether you are expecting analytics from a non-widget surface that is not represented here yet

Best escalation path

When in doubt:

1. validate the same behavior in Playground
2. confirm the agent policy in Agent Builder
3. confirm source readiness in Knowledge
4. only then debug the integration surface