Context deadline exceeded error lacks accessible details in Prometheus UI

Direct Answer

When a PromQL query exceeds --query.timeout, Prometheus returns a context deadline exceeded error in the backend logs, but the web UI currently shows only a generic “Query failed” banner. To give users—especially those relying on screen readers—a clear, accessible explanation, the UI should expose a sanitized, descriptive error message and use an ARIA live region so the failure is announced immediately.

Confirmed Facts

• The backend error string is context deadline exceeded when a query times out.
• Prometheus UI does not currently surface that string; it shows a generic banner.
• Prometheus exposes no per‑request timeout override; the global flag is the only configurable limit.
• Adding an ARIA role="alert" to the banner will cause screen readers to announce the message as soon as it appears.
• Exposing raw backend error strings can leak implementation details, so sanitization is required.

Likely Explanation

The lack of detail stems from the UI’s design choice to keep error handling simple and avoid leaking internal error messages. However, for accessibility and usability, a more descriptive message—e.g., “Query timed out after 30 s. Consider simplifying the query or increasing the timeout”—provides actionable insight.

Steps to Fix the Current UI (for this case)

1. Verify the Prometheus version. Run prometheus --version to confirm you’re on 2.46.x or later, where the UI source is web/ui.
2. Inspect the API response. Execute a heavy query that triggers a timeout, then open the browser’s DevTools → Network → /api/v1/query and confirm the JSON body contains errorType:"timeout" and error:"context deadline exceeded".
3. Update the React component. In web/ui/src/components/QueryResultBanner.jsx, replace the static string with a conditional that shows:

   {errorType === 'timeout' && 'Query timed out after 30 s. Try a simpler query or increase the timeout.'}

4. Add an ARIA live region. Wrap the banner in a <div role="alert"> so screen readers announce it immediately.
5. Sanitize the message. Ensure only the timeout reason is shown; strip any stack traces or internal identifiers.
6. Rebuild and redeploy. Run make build and restart Prometheus.
7. Test with a screen reader. Use NVDA or VoiceOver to confirm the banner is announced when a timeout occurs.

Per‑Request Timeout Consideration

Prometheus currently does not support a per‑request timeout via query parameters or headers. Implementing such a feature would require changes to the HTTP handler to read a custom header (e.g., X-Prometheus-Timeout) and wrap the query execution in a context with that deadline. This is a non‑trivial change and is not recommended for quick fixes. Instead, users can:

• Adjust the global --query.timeout flag if many queries need more time.
• Use a client‑side proxy that injects a longer timeout for specific users.

What We Need to Confirm

Could you confirm which Prometheus release you’re running? Knowing the exact version will help verify whether the UI already includes any of the suggested improvements in newer releases.