About

Imported from jeremylongshore/tons-of-skills-marketplace (skills/.curated/hex-common-errors/SKILL.md). Install upstream with npx skills add jeremylongshore/tons-of-skills-marketplace --skill hex-common-errors. Copyright stays with the author (MIT).

Hex Common Errors

Name: hex-common-errors
Author: jeremylongshore

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

# Test token
curl -s -o /dev/null -w "%{http_code}" \
  -H "Authorization: Bearer $HEX_API_TOKEN" \
  https://app.hex.tech/api/v1/projects

# List recent runs for a project
curl -s -H "Authorization: Bearer $HEX_API_TOKEN" \
  https://app.hex.tech/api/v1/project/PROJECT_ID/runs | python3 -m json.tool

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

Classify authentication, authorization, project lookup, validation, quota, timeout, and terminal-run errors before changing configuration.
Reproduce once with the safe probe and capture only status, latency, quota, and opaque run ID.
Check scope, parameter schema, project state, quota, and downstream connection health in that order.
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.

Error Handling

Treat unknown destination, failed redaction, access expansion, or repeated non-idempotent run as a stop condition. Cancel or restore the prior revision rather than retrying with broader scope.

Examples

status=429; project=proj-sandbox-12; correlation=run-opaque-11; action=bounded-backoff; safe_probe=recovered supports a safe handoff.

Resources

Hex API Reference

Next Steps

For debugging, see hex-debug-bundle.

Use it

Copy one of these into your project. Installing also returns the manifest and these snippets.

yaml

targets:
  - https://api.opensmartroute.ai/api/v1/registry/jeremylongshore-tons-of-skills-marketplace-hex-common-errors/manifest   # or paste the manifest below

Manifest

An Open Capability Manifest: the router reads it to know what this does, what it costs and when to pick it.

jeremylongshore-tons-of-skills-marketplace-hex-common-errors.ocm.jsonjson

{
  "ocm": "1",
  "id": "jeremylongshore-tons-of-skills-marketplace-hex-common-errors",
  "kind": "skill",
  "name": "hex-common-errors",
  "description": "Diagnose and fix Hex common errors and exceptions. Use when encountering Hex errors, debugging failed requests, or troubleshooting integration issues. Trigger with phrases like \"hex error\", \"fix hex\", \"hex not working\", \"debug hex\".",
  "publisher": "jeremylongshore",
  "version": "1.0.0",
  "capabilities": {
    "domains": [
      "coding",
      "customer_support"
    ],
    "tags": [
      "skill-md",
      "saas",
      "hex",
      "data",
      "analytics",
      "skills-sh"
    ],
    "languages": [
      "en"
    ]
  },
  "quality_prior": 0.6,
  "examples": [
    "Diagnose and fix Hex common errors and exceptions. Use when encountering Hex errors, debugging failed requests, or troubleshooting integration issues. Trigger with phrases like \"hex error\", \"fix hex\", \"hex not working\", \"debug hex\"."
  ],
  "primary": false,
  "metadata": {
    "source": {
      "provider": "skills.sh",
      "repository": "https://github.com/jeremylongshore/tons-of-skills-marketplace",
      "path": "skills/.curated/hex-common-errors/SKILL.md",
      "ref": "HEAD",
      "url": "https://github.com/jeremylongshore/tons-of-skills-marketplace/blob/HEAD/skills/.curated/hex-common-errors/SKILL.md",
      "key": "jeremylongshore/tons-of-skills-marketplace/skills/.curated/hex-common-errors/SKILL.md"
    },
    "compatibility": "Designed for Claude Code",
    "allowed_tools": [
      "Read,",
      "Grep,",
      "Bash(curl:*)"
    ],
    "license": "MIT"
  },
  "instructions": "# Hex Common Errors\n\n## Error Reference\n\n### 401 Unauthorized\n\n**Cause:** Token invalid, expired, or missing.\n**Fix:** Regenerate token in Hex workspace settings.\n\n### 403 Forbidden — Read-Only Token\n\n**Cause:** Token has \"Read projects\" scope but RunProject requires \"Run projects\".\n**Fix:** Create new token with \"Run projects\" scope.\n\n### 404 Not Found — Project\n\n**Cause:** Project ID wrong or project not published.\n**Fix:** Verify project ID. Only published projects can be run via API.\n\n### 429 Too Many Requests\n\n**Cause:** RunProject is limited to 20 requests/min, 60/hr.\n**Fix:** Queue runs",
  "cost": {
    "context_tokens": 712
  }
}

Fetch it by URL: GET /api/v1/registry/jeremylongshore-tons-of-skills-marketplace-hex-common-errors/manifest?version=1.0.0

Reviews

Star ratings from people who tried it. One review per account; edit yours any time.

No reviews yet. Install it, try it, and be the first to rate it.