Exa Debug Bundle

---
name: exa-debug-bundle
description: 'Collect Exa debug evidence for support tickets and troubleshooting.

  Use when encountering persistent issues, preparing support tickets,

  or collecting diagnostic information for Exa problems.

  Trigger with phrases like "exa debug", "exa support bundle",

  "collect exa logs", "exa diagnostic".

  '
allowed-tools: Read, Bash(grep:*), Bash(curl:*), Bash(tar:*), Bash(node:*), Grep
version: 1.11.0
license: MIT
author: Jeremy Longshore <jeremy@intentsolutions.io>
tags:
- saas
- exa
- debugging
compatibility: Designed for Claude Code
---
# Exa Debug Bundle

## Prerequisites

- An issue owner, affected environment, approved support/incident destination, and redaction rules.
- Permission to collect only the minimum diagnostic metadata; no raw tokens, secrets, customer queries, or full result content.

## Examples

For an unexpected search result, collect opaque correlation ID, environment, API/SDK version, query category (not text), request options, status class, latency, and timestamp. Reproduce with a sanitized query, review the bundle for tokens or private content, then share only through the approved channel.

## Current State

!`node --version 2>/dev/null || echo 'N/A'`
!`npm list exa-js 2>/dev/null | grep exa-js || echo 'exa-js not installed'`
!`echo "EXA_API_KEY: ${EXA_API_KEY:+SET (${#EXA_API_KEY} chars)}"`

## Overview

Collect all necessary diagnostic information for Exa support tickets. Exa error responses include a `requestId` field — always include it when contacting support at hello@exa.ai.

## Instructions

### Step 1: Quick Connectivity Test

```bash
set -euo pipefail

echo "=== Exa Connectivity Test ==="
echo "API Key: ${EXA_API_KEY:+SET (${#EXA_API_KEY} chars)}"
echo ""

# Test basic search endpoint
HTTP_CODE=$(curl -s -o /tmp/exa-debug.json -w "%{http_code}" \
  -X POST https://api.exa.ai/search \
  -H "x-api-key: $EXA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"debug connectivity test","numResults":1}')

echo "HTTP Status: $HTTP_CODE"
if [ "$HTTP_CODE" = "200" ]; then
  echo "Status: HEALTHY"
  python3 -c "import json; d=json.load(open('/tmp/exa-debug.json')); print(f'Results: {len(d.get(\"results\",[]))}')" 2>/dev/null
else
  echo "Status: UNHEALTHY"
  echo "Response:"
  cat /tmp/exa-debug.json | python3 -m json.tool 2>/dev/null || cat /tmp/exa-debug.json
fi
```

### Step 2: Capture Request/Response Details

```typescript
import Exa from "exa-js";

const exa = new Exa(process.env.EXA_API_KEY);

async function debugSearch(query: string) {
  const startTime = performance.now();
  try {
    const result = await exa.searchAndContents(query, {
      numResults: 3,
      text: { maxCharacters: 500 },
    });

    const duration = performance.now() - startTime;
    console.log("=== Debug Info ===");
    console.log(`Query: "${query}"`);
    console.log(`Duration: ${duration.toFixed(0)}ms`);
    console.log(`Results: ${result.results.length}`);
    console.log(`Has autoprompt: ${!!result.autopromptString}`);
    for (const r of result.results) {
      console.log(`  [${r.score.toFixed(3)}] ${r.title} (${r.url})`);
      console.log(`    Text: ${r.text ? `${r.text.length} chars` : "none"}`);
    }
  } catch (err: any) {
    const duration = performance.now() - startTime;
    console.error("=== Error Debug ===");
    console.error(`Query: "${query}"`);
    console.error(`Duration: ${duration.toFixed(0)}ms`);
    console.error(`Status: ${err.status || "unknown"}`);
    console.error(`Message: ${err.message}`);
    console.error(`RequestId: ${err.requestId || err.request_id || "none"}`);
    console.error(`Error tag: ${err.error_tag || err.tag || "none"}`);
  }
}
```

### Step 3: Create Debug Bundle Script

```bash
#!/bin/bash
set -euo pipefail
# exa-debug-bundle.sh

BUNDLE_DIR="exa-debug-$(date +%Y%m%d-%H%M%S)"
mkdir -p "$BUNDLE_DIR"

echo "=== Exa Debug Bundle ===" > "$BUNDLE_DIR/summary.txt"
echo "Generated: $(date -u +%Y-%m-%dT%H:%M:%SZ)" >> "$BUNDLE_DIR/summary.txt"

# Environment info
echo "" >> "$BUNDLE_DIR/summary.txt"
echo "--- Environment ---" >> "$BUNDLE_DIR/summary.txt"
echo "Node: $(node --version 2>/dev/null || echo 'N/A')" >> "$BUNDLE_DIR/summary.txt"
echo "npm: $(npm --version 2>/dev/null || echo 'N/A')" >> "$BUNDLE_DIR/summary.txt"
echo "OS: $(uname -a)" >> "$BUNDLE_DIR/summary.txt"
echo "EXA_API_KEY: ${EXA_API_KEY:+SET}" >> "$BUNDLE_DIR/summary.txt"

# SDK version
echo "" >> "$BUNDLE_DIR/summary.txt"
echo "--- SDK ---" >> "$BUNDLE_DIR/summary.txt"
npm list exa-js 2>/dev/null >> "$BUNDLE_DIR/summary.txt" || echo "exa-js not found" >> "$BUNDLE_DIR/summary.txt"

# API connectivity test
echo "" >> "$BUNDLE_DIR/summary.txt"
echo "--- API Test ---" >> "$BUNDLE_DIR/summary.txt"
HTTP_CODE=$(curl -s -o "$BUNDLE_DIR/api-response.json" -w "%{http_code}" \
  -X POST https://api.exa.ai/search \
  -H "x-api-key: ${EXA_API_KEY:-missing}" \
  -H "Content-Type: application/json" \
  -d '{"query":"debug test","numResults":1}' 2>/dev/null)
echo "HTTP Status: $HTTP_CODE" >> "$BUNDLE_DIR/summary.txt"

# Package bundle
tar -czf "$BUNDLE_DIR.tar.gz" "$BUNDLE_DIR"
echo "Bundle created: $BUNDLE_DIR.tar.gz"
echo ""
echo "IMPORTANT: Review $BUNDLE_DIR/summary.txt before sharing."
echo "Include the requestId from any error responses when contacting hello@exa.ai"
```

## Output

- `exa-debug-YYYYMMDD-HHMMSS.tar.gz` archive containing:
  - `summary.txt` — environment, SDK version, API connectivity
  - `api-response.json` — raw API response from test query

## Sensitive Data Handling

**Always redact before sharing:**

- API keys and tokens
- Query content containing PII
- Internal URLs or domain names

**Safe to include:**

- HTTP status codes and error tags
- `requestId` from error responses
- SDK and runtime versions
- Latency measurements

## Error Handling

| Issue | Cause | Solution |
|-------|-------|----------|
| `curl: command not found` | curl not installed | Install curl or use node script |
| Empty API response | Network firewall | Check outbound HTTPS to api.exa.ai |
| 401 in connectivity test | Bad API key | Regenerate at dashboard.exa.ai |
| Bundle script fails | Missing permissions | Run with `bash` not `sh` |

## Resources

- [Exa Error Codes](https://docs.exa.ai/reference/error-codes)
- [Exa Support](mailto:hello@exa.ai)

## Next Steps

For rate limit issues, see `exa-rate-limits`. For common error solutions, see `exa-common-errors`.