---

name: hex-debug-bundle description: '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".

' allowed-tools: Read, Bash(grep:), Bash(curl:), Bash(tar:*), Grep version: 1.6.0 license: MIT author: Jeremy Longshore jeremy@intentsolutions.io tags:

• saas
• hex
• data
• analytics compatibility: Designed for Claude Code

---

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();

Prerequisites

• An incident ID, bounded collection window, approved restricted destination, and sandbox project with safe probe parameters.
• A redaction policy excluding API tokens, SQL, cell output, dataset values, user identities, and connection metadata before evidence leaves the runtime.

Instructions

1. Collect only status, latency bands, run state, configuration revision, quota headers, and opaque project/run correlation IDs from the safe probe.
2. Run a redaction check before packaging and stop if output-bearing fields cannot be proven absent.
3. Compare aggregate results with the last known-good baseline, encrypt the bundle in the approved location, and grant minimum access.
4. Record owner and deletion date, then remove temporary artifacts after the incident window.

Output

Create a bundle manifest with incident ID, collection window, checks run, opaque correlation IDs, aggregate metrics, configuration revision, destination, owner, and retention date. Workspace data and credentials are prohibited.

Error Handling

Stop for failed redaction, unknown destination, or a command that would expose production output or credentials. Record the unavailable evidence class and escalate; do not bypass the collection policy.

Examples

incident=inc-opaque-21; window=15m; project=proj-sandbox-12; run=errored; latency=p95-420ms; destination=restricted-support; retention=7d is a useful redacted bundle summary.

Resources

• Hex Status

Next Steps

See hex-common-errors.