anthropics / anthropics/claude-agent-sdk-typescript

ANTHROPIC_LOG=debug corrupts SDK protocol - debug logs should go to stderr

Open
#157 1 comment 1 reaction 0 assignees View on GitHub
bug
Dominant language
Shell
Stars
1.8k
Forks
226
PR merge metrics
No merged PRs in 30d

Description

# `ANTHROPIC_LOG=debug` corrupts SDK protocol - debug logs should go to stderr

## Problem

Setting `ANTHROPIC_LOG=debug` breaks the SDK. Debug logs are written to stdout, corrupting the JSON protocol used for parent-child communication.

```typescript
const result = query({
prompt: "Hello",
options: {
env: { ...process.env, ANTHROPIC_LOG: "debug" },
},
});
// Error: CLI output was not valid JSON. Output: [log_71a72b] sending request {
```

This prevents users from debugging API-level issues (auth failures, rate limits, request/response inspection) when using the SDK.

## Root Cause

```
Agent SDK (parent) ←── stdout ──← CLI (child)

Protocol JSON + Anthropic SDK debug logs
(expected) (unexpected, breaks parsing)
```

The Anthropic HTTP client uses `console.log` for debug output → stdout. The SDK expects stdout to contain only protocol JSON.

## Suggested Fix

Configure the Anthropic client inside the CLI to use stderr for logging:

```typescript
const client = new Anthropic({
logger: {
debug: (msg) => process.stderr.write(`[debug] ${msg}\n`),
info: (msg) => process.stderr.write(`[info] ${msg}\n`),
warn: (msg) => process.stderr.write(`[warn] ${msg}\n`),
error: (msg) => process.stderr.write(`[error] ${msg}\n`),
},
});
```

This preserves stdout for protocol communication while routing debug output to stderr, where the SDK already captures it via the `stderr` callback.

## Why This Matters

When things go wrong (auth issues, rate limits, timeouts), `ANTHROPIC_LOG=debug` is the standard way to diagnose problems with the Anthropic API. Having this broken in the Agent SDK makes debugging significantly harder. Users expect environment variables that work with the base SDK to also work here.

## Workaround

We're currently using `spawnClaudeCodeProcess` to intercept stdout and filter non-JSON lines to stderr. Happy to share the implementation if helpful, but this should be unnecessary - debug logs belong on stderr.

## Environment

- `@anthropic-ai/claude-agent-sdk`: 0.2.23
- Node.js: v24.3.0

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.