---
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

```bash
#!/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

```bash
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

```typescript
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](https://status.hex.tech)

## Next Steps

See `hex-common-errors`.