Mistral AI Debug Bundle Skill

Mistral AI Debug Bundle

Current State

!node --version 2>/dev/null || echo 'N/A' !python3 --version 2>/dev/null || echo 'N/A'

Overview

Collect all necessary diagnostic information for Mistral AI support tickets. Creates a redacted bundle with environment info, SDK versions, API connectivity test, available models, and recent error logs.

Prerequisites

Mistral AI SDK installed
Access to application logs
MISTRAL_API_KEY set (for connectivity test)

Instructions

Step 1: Complete Debug Script

#!/bin/bash
# mistral-debug-bundle.sh — Creates redacted support bundle
set -e

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

echo "Creating Mistral AI debug bundle..."

# === Environment Info ===
cat > "$BUNDLE_DIR/summary.txt" << EOF
=== Mistral AI Debug Bundle ===
Generated: $(date -u +%Y-%m-%dT%H:%M:%SZ)
Hostname: $(hostname)

--- Environment ---
Node.js: $(node --version 2>/dev/null || echo 'not installed')
Python: $(python3 --version 2>/dev/null || echo 'not installed')
npm: $(npm --version 2>/dev/null || echo 'not installed')
OS: $(uname -a)
MISTRAL_API_KEY: ${MISTRAL_API_KEY:+[SET, length=${#MISTRAL_API_KEY}]}${MISTRAL_API_KEY:-[NOT SET]}
EOF

# === SDK Versions ===
echo -e "\n--- SDK Versions ---" >> "$BUNDLE_DIR/summary.txt"
npm list @mistralai/mistralai 2>/dev/null >> "$BUNDLE_DIR/summary.txt" \
  || echo "Node SDK: not installed" >> "$BUNDLE_DIR/summary.txt"
pip show mistralai 2>/dev/null | grep -E "^(Name|Version)" >> "$BUNDLE_DIR/summary.txt" \
  || echo "Python SDK: not installed" >> "$BUNDLE_DIR/summary.txt"

# === API Connectivity ===
echo -e "\n--- API Connectivity ---" >> "$BUNDLE_DIR/summary.txt"
if [ -n "${MISTRAL_API_KEY:-}" ]; then
  HTTP_STATUS=$(curl -s -o "$BUNDLE_DIR/api-response.json" -w "%{http_code}" \
    -H "Authorization: Bearer ${MISTRAL_API_KEY}" \
    https://api.mistral.ai/v1/models 2>/dev/null)
  echo "HTTP Status: $HTTP_STATUS" >> "$BUNDLE_DIR/summary.txt"

  if [ "$HTTP_STATUS" = "200" ]; then
    echo -e "\n--- Available Models ---" >> "$BUNDLE_DIR/summary.txt"
    jq -r '.data[].id' "$BUNDLE_DIR/api-response.json" >> "$BUNDLE_DIR/summary.txt" 2>/dev/null
  fi
  rm -f "$BUNDLE_DIR/api-response.json"
else
  echo "Skipped (no API key)" >> "$BUNDLE_DIR/summary.txt"
fi

# === Dependencies ===
if [ -f "package.json" ]; then
  echo -e "\n--- Dependencies ---" >> "$BUNDLE_DIR/summary.txt"
  jq '{dependencies, devDependencies}' package.json 2>/dev/null >> "$BUNDLE_DIR/summary.txt"
fi

# === Recent Logs (redacted) ===
echo "--- Recent Logs (redacted) ---" > "$BUNDLE_DIR/logs.txt"
if [ -d "logs" ]; then
  grep -i "mistral\|error\|429\|401\|500" logs/*.log 2>/dev/null | tail -100 >> "$BUNDLE_DIR/logs.txt"
fi

# === Config (redacted) ===
if [ -f ".env" ]; then
  sed 's/=.*/=***REDACTED***/' .env > "$BUNDLE_DIR/config-redacted.txt"
fi

# === Reproduction Script ===
cat > "$BUNDLE_DIR/reproduce.sh" << 'SCRIPT'
#!/bin/bash
set -euo pipefail
curl -X POST https://api.mistral.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${MISTRAL_API_KEY}" \
  -d '{"model":"mistral-small-latest","messages":[{"role":"user","content":"ping"}]}' 2>&1
echo -e "\nExit code: $?"
SCRIPT
chmod +x "$BUNDLE_DIR/reproduce.sh"

# === Package ===
tar -czf "$BUNDLE_DIR.tar.gz" "$BUNDLE_DIR"
rm -rf "$BUNDLE_DIR"
echo "Bundle: $BUNDLE_DIR.tar.gz"
echo "IMPORTANT: Review for sensitive data before sharing!"

Step 2: TypeScript Debug Helper

import { Mistral } from '@mistralai/mistralai';

interface DebugInfo {
  timestamp: string;
  nodeVersion: string;
  apiKeySet: boolean;
  apiKeyLength: number;
  connectivity: 'ok' | 'auth_error' | 'network_error' | 'unknown_error';
  availableModels: string[];
  latencyMs: number;
  lastError?: { message: string; status?: number };
}

async function collectDebugInfo(error?: Error): Promise<DebugInfo> {
  const info: DebugInfo = {
    timestamp: new Date().toISOString(),
    nodeVersion: process.version,
    apiKeySet: !!process.env.MISTRAL_API_KEY,
    apiKeyLength: process.env.MISTRAL_API_KEY?.length ?? 0,
    connectivity: 'unknown_error',
    availableModels: [],
    latencyMs: 0,
  };

  if (error) {
    info.lastError = {
      message: error.message,
      status: (error as any).status,
    };
  }

  if (info.apiKeySet) {
    const start = performance.now();
    try {
      const client = new Mistral({ apiKey: process.env.MISTRAL_API_KEY });
      const models = await client.models.list();
      info.connectivity = 'ok';
      info.availableModels = models.data?.map(m => m.id) ?? [];
      info.latencyMs = Math.round(performance.now() - start);
    } catch (e: any) {
      info.latencyMs = Math.round(performance.now() - start);
      info.connectivity = e.status === 401 ? 'auth_error' : 'network_error';
    }
  }

  return info;
}

// Usage in catch blocks
try {
  await client.chat.complete({ model: 'mistral-small-latest', messages });
} catch (error) {
  const debug = await collectDebugInfo(error as Error);
  console.error('Debug info:', JSON.stringify(debug, null, 2));
}

Step 3: Request/Response Logger for Debugging

function createDebugClient(): Mistral {
  const client = new Mistral({ apiKey: process.env.MISTRAL_API_KEY });

  // Wrap chat.complete to log request/response metadata
  const originalComplete = client.chat.complete.bind(client.chat);
  client.chat.complete = async (params: any) => {
    const start = performance.now();
    console.debug('[MISTRAL REQUEST]', {
      model: params.model,
      messageCount: params.messages?.length,
      hasTools: !!params.tools?.length,
      temperature: params.temperature,
    });

    try {
      const response = await originalComplete(params);
      console.debug('[MISTRAL RESPONSE]', {
        durationMs: Math.round(performance.now() - start),
        finishReason: response.choices?.[0]?.finishReason,
        usage: response.usage,
        hasToolCalls: !!response.choices?.[0]?.message?.toolCalls?.length,
      });
      return response;
    } catch (error: any) {
      console.debug('[MISTRAL ERROR]', {
        durationMs: Math.round(performance.now() - start),
        status: error.status,
        message: error.message,
      });
      throw error;
    }
  };

  return client;
}

Sensitive Data Rules

ALWAYS REDACT: API keys, passwords, PII (emails, names), internal URLs SAFE TO INCLUDE: Error messages, stack traces, SDK versions, HTTP status codes, model IDs

Output

mistral-debug-YYYYMMDD-HHMMSS.tar.gz containing:
- summary.txt — environment, SDK versions, API status
- logs.txt — recent redacted error logs
- config-redacted.txt — config with secrets masked
- reproduce.sh — minimal reproduction script

Error Handling

| Item | Purpose | |------|---------| | Environment versions | Compatibility check | | SDK version | Version-specific bug identification | | API connectivity test | Network/auth diagnosis | | Available models | Key scope verification | | Error logs (redacted) | Root cause analysis |

Resources

Next Steps

For rate limit issues, see mistral-rate-limits. For common errors, see mistral-common-errors.

Agent Skills: Mistral AI Debug Bundle

Install this agent skill to your local

Skill Files