[QuickSight Agent UI Bug] Document upload fails with clientReferenceId regex validation error

[Jerry_Yeh]

Issue Description

When attempting to upload a markdown reference file (KAST_Instructions.md, 14.5 KB) to an Amazon QuickSight Q Chat Agent (Agent ID: d5ce4910-8c43-438a-a783-7b294f393001), the web console consistently fails with a client-side/API validation error. Furthermore, attempting the same action via the Amazon QuickSight Desktop Application shows a successful save state in the UI, but fails to persist or sync the uploaded document to the backend agent state.

Error Message (Web Console)

Plaintext

Upload error
1 validation error detected: Value at 'clientReferenceId' failed to satisfy constraint: Member must satisfy regular expression pattern: [A-Za-z0-9_\-.:]+

Key Troubleshooting Findings & Evidence

1. Filename Formatting: Verified that the issue persists regardless of the filename (tested standard names like 12345.md, instructions.md, and KAST_Instructions.md). The regex constraint failure is triggered by an internal payload parameter (clientReferenceId) generated by the QuickSight frontend, not the user-supplied filename.

2. Environment Isolation: Reproduced in standard Chrome sessions, Incognito mode, and across different AWS accounts/regions (ap-southeast-2).

3. Desktop Application UI/Sync Inconsistency:

   • In the QuickSight Desktop App, uploading the same .md file in the agent config panel shows the file attached, and the Save button transitions to a disabled state (indicating saved changes).

   • However, upon switching tabs (e.g., to Agent Files) or reopening the agent in the Web Console, the document is missing.

   • Subsequent edits/saves in the Web Console immediately re-trigger the original clientReferenceId error popup, confirming the backend never ingested the file reference.

Steps to Reproduce

1. Navigate to Amazon QuickSight Q $\rightarrow$ Chat Agents $\rightarrow$ Select or Edit an Agent.

2. Scroll down to Reference Documents / Additional Documents.

3. Click Browse files or drag-and-drop a supported file (e.g., .md, .pdf, .txt).

4. Result (Web): The UI immediately throws the clientReferenceId validation error toast message.

5. Result (Desktop App): The UI shows the file attached and allows saving, but checking the Agent Files tab reveals the file was not actually synced or stored in the agent’s knowledge/reference state.

Impact

Users are unable to leverage document attachments for agent behavior grounding. As a temporary workaround, full document contents must be manually pasted directly into the Instructions text box.

Requested Action

1. Fix the payload generator in the QuickSight Q Agent web console to ensure clientReferenceId values satisfy the regex pattern [A-Za-z0-9_\-.:]+.

2. Fix the Desktop App’s state handling so it accurately reflects backend upload failures instead of falsely indicating a successful save.

   

[JacobR]

Hi @Jerry_Yeh and welcome to the Quick Community!

Thank you for the detailed explanation! From how you laid everything out, this definitely sounds like a bug on the Quick Sight side. The clientReferenceId is generated internally by the console’s frontend code before it hits the API, and whatever value it’s constructing clearly contains characters outside the allowed [A-Za-z0-9_\-.:]+ pattern. Your troubleshooting confirms that perfectly since the filename itself is irrelevant. The secondary issue with the Desktop App showing a successful save without actually persisting to the backend sounds to be a separate bug as well.

Unfortunately, there is nothing much I can do regarding this instance. I would highly recommend opening an AWS Support case. Please refer to this resource on how to create a support ticket (Case management - AWS Support).

In the meantime, your workaround of pasting document content directly into the Instructions/Persona text box is the right call. Alternatively, an additional workaround you could also try is the reference documents approach via the API (using update_agent with the appropriate parameters) to bypass the console entirely, though the public API docs don’t seem to expose the reference document upload path directly yet.