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

If the default agent suddenly retrieves nothing at all (every answer ungrounded, sources always none), its saved policy may have failed validation — Calypso fails closed on a malformed stored policy rather than widening retrieval. Re-save the agent's configuration in Agent Builder to rewrite a valid policy.

Check:

• whether the source is truly indexed
• whether the source pool is too broad or too weak
• whether the selected agent 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 source's ready flag is true — GET /v1/sources/{id} (alias: GET /v1/knowledge/files/{file_id}) is the one-bit check
• whether the upload response says queued, accepted, or indexing instead of active
• for task detail, poll 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. The ready flag is the authoritative check: it is true only after both indexing and bucket sync complete, so a source that reports ready: true is retrievable through its bucket.

If the file reports active but answers never cite it, verify directly against the search provider:

GET /v1/sources/{id}?verify=gemini

The gemini object in the response shows the live document state in the search index (STATE_ACTIVE means the document is active in Gemini; STATE_FAILED means the provider could not process the file — re-upload it, and consider reducing image size for very large scans). This is the ground truth for provider state when recorded status and observed behavior disagree. It is not the whole retrieval story: bucket-scoped answers additionally require the file's bucketSyncStatus to be active for the bucket the agent searches.

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-file or calypso-upload-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 agent is not behaving as expected

Check:

• the exact model ID being called
• whether the agent still exists
• whether the intended agent 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 agent 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