Agent skill · data analytics · jeremylongshore
hex-common-errors
Diagnose and fix Hex common errors and exceptions.
Why this skill is useful
Provides specific commands and troubleshooting steps for common Hex errors that the AI wouldn't reliably generate on its own.
What it needs
Requires bash installed locally. Requires hex account access. About 2k tokens when loaded. Last updated 2026-08-07. 2,604 stars on the source repository.
What this skill does
Hex Common Errors Error Reference 401 Unauthorized Cause: Token invalid, expired, or missing. Fix: Regenerate token in Hex workspace settings. 403 Forbidden — Read-Only Token Cause: Token has "Read projects" scope but RunProject requires "Run projects". Fix: Create new token with "Run projects" scope. 404 Not Found — Project Cause: Project ID wrong or project not published. Fix: Verify project ID. Only published projects can be run via API. 429 Too Many Requests Cause: RunProject is limited to 20 requests/min, 60/hr. Fix: Queue runs with delays. See hex-rate-limits. Run Status: ERRORED Cause: SQL query, Python code, or connection error in the project. Fix: Open the project in Hex UI and check the error in the run history. Run Status: KILLED Cause: Run exceeded timeout or was manually cancelled. Fix: Optimize slow queries. Increase timeout in API trigger. Quick Diagnostics Overview This reference triages project-run failures using status, aggregate telemetry, and opaque run IDs. It does not authorize copying SQL, cell output, data previews, or tokens into a ticket. Prerequisites A safe sandbox probe, redacted correlation ID, endpoint class, and HTTP or terminal-run status. A scoped read-only diagnostic credential and named owner for any project, schedule, or access change. Instructions 1. Classify authentication, authorization, project lookup, validation, quota, timeout, and terminal-run errors before changing configuration. 2. Reproduce once with the safe probe and capture only status, latency, quota, and opaque run ID. 3. Check scope, parameter schema, project state, quota, and downstream connection health in that order. 4. Make one reversible change at a time and escalate a redacted bundle when the error persists. Output Return error class, correlation ID, project scope, probe outcome, remediation attempted, and next owner. Do not include SQL, output, credentials, or identities. …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills jeremylongshore/hex-common-errors