Hex Debug Bundle Skill | Agent Skills

Hex Debug Bundle

Overview

Collect Hex API connectivity status, project listing, run history, data connection health, and rate limit state into a single diagnostic archive. This bundle helps troubleshoot failed notebook runs, stale data connections, scheduled run failures, and API authentication issues.

Debug Collection Script

#!/bin/bash
set -euo pipefail
BUNDLE="debug-hex-$(date +%Y%m%d-%H%M%S)"
mkdir -p "$BUNDLE"

# Environment check
echo "=== Hex Debug Bundle ===" | tee "$BUNDLE/summary.txt"
echo "Generated: $(date -u +%Y-%m-%dT%H:%M:%SZ)" >> "$BUNDLE/summary.txt"
echo "HEX_API_KEY: ${HEX_API_KEY:+[SET]}" >> "$BUNDLE/summary.txt"

# API connectivity
HTTP=$(curl -s -o /dev/null -w "%{http_code}" \
  -H "Authorization: Bearer ${HEX_API_KEY}" \
  https://app.hex.tech/api/v1/projects 2>/dev/null || echo "000")
echo "API Status: HTTP $HTTP" >> "$BUNDLE/summary.txt"

# Project listing
curl -s -H "Authorization: Bearer ${HEX_API_KEY}" \
  "https://app.hex.tech/api/v1/projects" \
  > "$BUNDLE/projects.json" 2>&1 || true

# Recent runs (across projects)
curl -s -H "Authorization: Bearer ${HEX_API_KEY}" \
  "https://app.hex.tech/api/v1/runs?limit=10" \
  > "$BUNDLE/recent-runs.json" 2>&1 || true

# Data connections and rate limit headers
curl -s -D "$BUNDLE/rate-headers.txt" -H "Authorization: Bearer ${HEX_API_KEY}" \
  "https://app.hex.tech/api/v1/connections" > "$BUNDLE/connections.json" 2>&1 || true

tar -czf "$BUNDLE.tar.gz" "$BUNDLE" && rm -rf "$BUNDLE"
echo "Bundle: $BUNDLE.tar.gz"

Analyzing the Bundle

tar -xzf debug-hex-*.tar.gz
cat debug-hex-*/summary.txt                       # Auth + connectivity
jq '.[] | {id, title, status}' debug-hex-*/projects.json   # Project inventory
jq '.[] | {id, status, started_at}' debug-hex-*/recent-runs.json  # Run history
jq '.[] | {name, type, status}' debug-hex-*/connections.json      # Data source health

Common Issues

| Symptom | Check in Bundle | Fix | |---------|----------------|-----| | API returns 401 | summary.txt shows HTTP 401 | Regenerate API token in Hex workspace Settings > API | | Run stuck in pending | recent-runs.json shows pending status for >5 min | Check compute quota; cancel and re-trigger the run | | Data connection failed | connections.json shows error on a source | Re-authenticate the connection; verify DB credentials haven't expired | | Scheduled run not firing | recent-runs.json missing expected scheduled entries | Check project schedule in Hex UI; verify project is published | | Rate limited (429) | rate-headers.txt shows Retry-After | Reduce API polling; batch project queries where possible |

Automated Health Check

async function checkHex(): Promise<void> {
  const key = process.env.HEX_API_KEY;
  if (!key) { console.error("[FAIL] HEX_API_KEY not set"); return; }

  const res = await fetch("https://app.hex.tech/api/v1/projects", {
    headers: { Authorization: `Bearer ${key}` },
  });
  console.log(`[${res.ok ? "OK" : "FAIL"}] API: HTTP ${res.status}`);

  if (res.ok) {
    const data = await res.json();
    console.log(`[INFO] Projects accessible: ${Array.isArray(data) ? data.length : 0}`);
  }
}
checkHex();

Resources

Hex Status

Next Steps

See hex-common-errors.

Agent Skills: Hex Debug Bundle

Install this agent skill to your local

Skill Files