exa-debug-bundle

Exa Debug Bundle

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 [email protected].

Instructions

Step 1: Quick Connectivity Test

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

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

#!/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 [email protected]"

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
• Exa Support

Next Steps

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