Collect Hex debug evidence for support tickets and troubleshooting. Use when encountering persistent issues, preparing support tickets, or collecting diagnostic information for Hex problems. Trigger with phrases like "hex debug", "hex support bundle", "collect hex logs", "hex diagnostic".
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.
#!/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"
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
| 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 |
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();
See hex-common-errors.