Debugging

Every tool call in CodeSpar is logged with input, output, duration, server, and status. Use the dashboard logs and API to debug failed calls, trace execution, and monitor performance.

Finding your debugging info

Navigate to your project's Logs page in the dashboard to see all tool executions:

Tool call anatomy

Every ToolResult returned by session.execute() contains debugging information:

const result = await session.execute("codespar_pay", {
  method: "pix",
  amount: 15000,
  currency: "BRL",
});

console.log(result);

{
  "success": true,
  "data": { "payment_id": "pay_xyz789", "status": "pending" },
  "error": null,
  "duration": 430,
  "server": "asaas",
  "tool": "codespar_pay",
  "tool_call_id": "tc_9f8e7d6c",
  "called_at": "2026-04-17T15:30:00Z"
}

Key fields for debugging:

• duration — Latency in milliseconds. High values may indicate provider issues
• server — Which MCP server handled the call (useful when meta-tools auto-route)
• tool_call_id — Unique identifier for cross-referencing with dashboard logs
• error — Error message if success is false

Debugging common issues

Tool call failed

{
  "success": false,
  "data": null,
  "error": "Invalid parameter: amount must be a positive integer",
  "duration": 12,
  "server": "codespar",
  "tool": "codespar_pay"
}

Low duration + error from codespar server = validation error. Check the tool's input_schema for required fields and types.

Provider timeout

{
  "success": false,
  "data": null,
  "error": "Upstream timeout: asaas did not respond within 30000ms",
  "duration": 30012,
  "server": "asaas",
  "tool": "codespar_pay"
}

High duration + timeout error = the provider's API is slow or down. CodeSpar retries automatically, but if retries also fail, the error is returned.

Authentication expired

{
  "success": false,
  "data": null,
  "error": "OAuth token expired for server 'mercadopago'. Re-authorize via session.authorize('mercadopago')",
  "duration": 45,
  "server": "mercadopago",
  "tool": "codespar_pay"
}

Auth error = the OAuth token for a server has expired. Call session.authorize(serverId) to trigger re-authentication.

Rate limited

{
  "success": false,
  "data": null,
  "error": "Rate limited by provider: melhor-envio (180/200 calls). Resets in 14 minutes.",
  "duration": 22,
  "server": "melhor-envio",
  "tool": "codespar_ship"
}

Rate limit error = the provider's API has rate limits. Wait for the reset window or reduce call frequency.

API access to logs

Retrieve tool call logs programmatically:

curl https://api.codespar.dev/v1/sessions/ses_abc123/logs \
  -H "Authorization: Bearer csk_live_abc123..."

{
  "data": [
    {
      "id": "tc_9f8e7d6c",
      "tool": "ZOOP_CREATE_CHARGE",
      "server": "zoop",
      "status": "success",
      "duration_ms": 340,
      "input": { "amount": 15000, "currency": "BRL" },
      "output": { "charge_id": "chg_abc123", "status": "pending" },
      "called_at": "2026-04-17T15:30:00Z",
      "user": "agent-commerce"
    }
  ],
  "total": 18,
  "session_id": "ses_abc123"
}

Filter logs

Reporting a bug

Your debugging info is tied to your project and helps us trace what happened and fix the issue faster. When you file an issue, paste these three fields:

Paste them into github.com/codespar/codespar-core/issues/new along with the expected vs actual behavior.

**Project:** proj_abc123
**Session:** ses_xyz789
**Tool call:** tc_9f8e7d6c
**When:** 2026-04-17T15:30:00Z

**Expected:** codespar_pay returns `success: true` with a payment_id
**Actual:** `success: false` with error "Upstream timeout"

Steps to reproduce:
1. ...

Observability dashboard

The Observability page provides real-time monitoring:

• Deployments — Build status, success rate, average build time
• Error tracking — Sentry integration with drill-down to issues
• Smart alerts — AI-analyzed alerts with severity (P1-P4) and suggested fixes
• Live logs — Real-time log streaming via SSE with level and source filtering

Best practices

1. Always check success before using data. A false success means data is null.

2. Log tool_call_id in your application for cross-referencing with the dashboard.

3. Monitor duration to detect provider degradation early. Set alerts for p95 > 5s.

4. Use try/finally to ensure session.close() runs even when tool calls fail.

5. Check the dashboard when debugging production issues — it shows the full input/output of every call.

Next steps

• Sessions — Session lifecycle and error handling
• Tools API — Execute tools and inspect responses
• Billing — Usage tracking and cost monitoring