Cohere Debug Bundle Skill

Cohere Debug Bundle

Overview

Collect all diagnostic information needed to resolve Cohere API v2 issues. Generates a support-ready bundle with environment info, request/response logs, and SDK version data.

Prerequisites

cohere-ai SDK installed
Access to application logs
curl and jq available

Instructions

Step 1: Create Debug Bundle Script

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

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

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

Step 2: Collect Environment and SDK Info

# Runtime versions
echo "--- Runtime ---" >> "$BUNDLE_DIR/summary.txt"
node --version >> "$BUNDLE_DIR/summary.txt" 2>&1 || echo "Node.js: not found" >> "$BUNDLE_DIR/summary.txt"
python3 --version >> "$BUNDLE_DIR/summary.txt" 2>&1 || echo "Python: not found" >> "$BUNDLE_DIR/summary.txt"

# SDK version
echo "--- SDK ---" >> "$BUNDLE_DIR/summary.txt"
npm list cohere-ai 2>/dev/null >> "$BUNDLE_DIR/summary.txt" || echo "cohere-ai: not installed (npm)" >> "$BUNDLE_DIR/summary.txt"
pip show cohere 2>/dev/null | grep Version >> "$BUNDLE_DIR/summary.txt" || echo "cohere: not installed (pip)" >> "$BUNDLE_DIR/summary.txt"

# API key status (never log the actual key)
echo "--- Auth ---" >> "$BUNDLE_DIR/summary.txt"
if [ -n "${CO_API_KEY:-}" ]; then
  echo "CO_API_KEY: SET (${#CO_API_KEY} chars, starts with ${CO_API_KEY:0:4}...)" >> "$BUNDLE_DIR/summary.txt"
else
  echo "CO_API_KEY: NOT SET" >> "$BUNDLE_DIR/summary.txt"
fi

Step 3: Test API Connectivity

echo "--- API Connectivity ---" >> "$BUNDLE_DIR/summary.txt"

# Test each endpoint
for endpoint in chat embed rerank classify; do
  STATUS=$(curl -s -o /dev/null -w "%{http_code}" \
    -X POST "https://api.cohere.com/v2/$endpoint" \
    -H "Authorization: Bearer ${CO_API_KEY:-invalid}" \
    -H "Content-Type: application/json" \
    -d '{}' 2>/dev/null || echo "UNREACHABLE")
  echo "$endpoint: HTTP $STATUS" >> "$BUNDLE_DIR/summary.txt"
done

# Check service status
echo "" >> "$BUNDLE_DIR/summary.txt"
echo "--- Service Status ---" >> "$BUNDLE_DIR/summary.txt"
curl -s https://status.cohere.com/api/v2/status.json 2>/dev/null | \
  python3 -c "import sys,json; d=json.load(sys.stdin); print(f'Status: {d[\"status\"][\"description\"]}')" \
  >> "$BUNDLE_DIR/summary.txt" 2>/dev/null || echo "Status page: unreachable" >> "$BUNDLE_DIR/summary.txt"

Step 4: Capture Request/Response Debug

// Add to your app for temporary debug logging
import { CohereClientV2, CohereError } from 'cohere-ai';
import fs from 'fs';

const debugLog: Array<{
  timestamp: string;
  endpoint: string;
  model?: string;
  status: 'success' | 'error';
  durationMs: number;
  error?: string;
  tokensUsed?: { input: number; output: number };
}> = [];

async function debugWrappedCall<T>(
  endpoint: string,
  model: string | undefined,
  fn: () => Promise<T>
): Promise<T> {
  const start = Date.now();
  try {
    const result = await fn();
    debugLog.push({
      timestamp: new Date().toISOString(),
      endpoint,
      model,
      status: 'success',
      durationMs: Date.now() - start,
    });
    return result;
  } catch (err) {
    debugLog.push({
      timestamp: new Date().toISOString(),
      endpoint,
      model,
      status: 'error',
      durationMs: Date.now() - start,
      error: err instanceof CohereError
        ? `${err.statusCode}: ${err.message}`
        : String(err),
    });
    throw err;
  }
}

// Dump log to file
function exportDebugLog(path: string) {
  fs.writeFileSync(path, JSON.stringify(debugLog, null, 2));
}

Step 5: Package and Redact

# Collect application logs (redacted)
grep -i "cohere\|CohereError\|CO_API_KEY" /var/log/app/*.log 2>/dev/null | \
  sed 's/Bearer [^ ]*/Bearer ***REDACTED***/g' | \
  tail -100 > "$BUNDLE_DIR/app-logs.txt"

# Package bundle
tar -czf "$BUNDLE_DIR.tar.gz" "$BUNDLE_DIR"
echo "Bundle: $BUNDLE_DIR.tar.gz ($(du -h "$BUNDLE_DIR.tar.gz" | cut -f1))"
rm -rf "$BUNDLE_DIR"

Bundle Contents

| File | Contents | Sensitive? | |------|----------|-----------| | summary.txt | Runtime, SDK version, API key status, connectivity | No | | app-logs.txt | Recent Cohere-related log lines (redacted) | Redacted | | debug-log.json | Request timing, errors, token usage | No |

Always redact: API keys, bearer tokens, PII in request bodies. Safe to include: Error messages, HTTP status codes, SDK versions, timing data.

Quick One-Liner Diagnostics

# Full diagnostic in one command
echo "Node: $(node -v 2>/dev/null || echo N/A) | SDK: $(npm list cohere-ai 2>/dev/null | grep cohere || echo N/A) | Key: ${CO_API_KEY:+SET} | API: $(curl -s -o /dev/null -w '%{http_code}' -H "Authorization: Bearer ${CO_API_KEY:-x}" https://api.cohere.com/v2/chat -H 'Content-Type: application/json' -d '{}' 2>/dev/null)"

Error Handling

| Item | Purpose | |------|---------| | SDK version | Identify version-specific bugs | | API key status | Auth configuration issues | | Endpoint connectivity | Network/firewall problems | | Request timing | Latency and timeout diagnosis | | Error codes | Classify issue type (4xx vs 5xx) |

Resources

Next Steps

For rate limit issues, see cohere-rate-limits.

Agent Skills: Cohere Debug Bundle

Install this agent skill to your local

Skill Files