Qbusiness Diagnostics

Amazon Q Business Diagnostics

When to use

Any Amazon Q Business investigation — application setup, data source connectors, retrieval quality, guardrails, plugins, web experience, or IAM Identity Center integration.

Investigation workflow

Step 1 — Collect and triage

aws qbusiness list-applications
aws qbusiness get-application --application-id <app-id>
aws qbusiness list-indices --application-id <app-id>
aws qbusiness list-data-sources --application-id <app-id> --index-id <idx-id>

Step 2 — Domain deep dive

aws qbusiness list-data-source-sync-jobs --application-id <app-id> --index-id <idx-id> --data-source-id <ds-id>
aws qbusiness list-plugins --application-id <app-id>
aws qbusiness get-web-experience --application-id <app-id> --web-experience-id <we-id>
aws qbusiness list-retrievers --application-id <app-id>

Step 3 — Detailed investigation

aws qbusiness get-chat-controls-configuration --application-id <app-id>
aws cloudtrail lookup-events --lookup-attributes AttributeKey=EventSource,AttributeValue=qbusiness.amazonaws.com --max-results 20

Read references/guardrails.md before concluding on any Q Business issue.

Gotchas: Amazon Q Business

• Q Business requires IAM Identity Center. Applications cannot function without SSO.
• Data source sync is asynchronous. Documents are not available until sync completes.
• Guardrails (topic controls) can block legitimate queries. Test thoroughly.
• Plugins extend Q Business with actions. Plugin errors affect conversation flow.
• Web experience requires proper IAM Identity Center user assignment.
• Retrieval quality depends on document quality and chunking strategy.

Anti-hallucination rules

1. Always cite application IDs, data source IDs, or API responses as evidence.
2. Q Business requires IAM Identity Center. Never suggest it works without SSO.
3. Sync must complete before documents are available for chat.
4. Spend no more than 2 minutes on any single hypothesis. Pivot if inconclusive.

14 runbooks