thedixitjain 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
Next Steps
See hex-common-errors.
Source: jeremylongshore/claude-code-plugins-plus-skills → skills/.curated/hex-debug-bundle/SKILL.md
Also appears in: jeremylongshore/claude-code-plugins-plus-skills/plugins/saas-packs/hex-pack/skills/hex-debug-bundle/SKILL.md