Menu
Comprehensive guide for debugging Claude Agent SDK errors, TypedDict contracts, and internal SDK processing issues
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
| name | Claude SDK Debugging |
| description | Comprehensive guide for debugging Claude Agent SDK errors, TypedDict contracts, and internal SDK processing issues |
| keywords | ["claude-sdk","sdk-error","mcp","typeddict","serialization","json-error","sdk-debugging"] |
CRITICAL: User-facing errors don't show root cause. Always check log files.
# Check error logs
tail -50 logs/errors.log
# Grep for specific error
grep "JSON serializable" logs/errors.log | tail -5
# Check recent errors
tail -100 logs/errors.log | grep -A 20 "ERROR"
Why: SDK errors surface deep in internal code. Full tracebacks show:
Once you have the traceback, find the SDK source file:
# Find SDK files in virtual environment
find .venv/lib -name "subprocess_cli.py" -path "*/claude_agent_sdk/*"
# Or in global Python packages
find /Users/$USER/.local/lib -name "*sdk*"
Read the SDK code at the failure point to understand:
Error: Object of type Server is not JSON serializable
Traceback shows: subprocess_cli.py:169 - json.dumps({"mcpServers": servers_for_cli})
Read SDK source at line 154-169:
if isinstance(config, dict) and config.get("type") == "sdk":
# For SDK servers, pass everything except the instance field
sdk_config = {k: v for k, v in config.items() if k != "instance"}
servers_for_cli[name] = sdk_config
else:
servers_for_cli[name] = config
# Line 169: JSON serialization
json.dumps({"mcpServers": servers_for_cli})
Root cause: SDK strips instance field but only if:
config.get("type") == "sdk" (must have type key)k != "instance" (must use instance key, not server)# Correct structure
McpSdkServerConfig(
type="sdk", # SDK checks: config.get("type") == "sdk"
name="server_name", # Server identifier
instance=server # SDK strips before JSON: k != "instance"
)
# Wrong - causes JSON serialization error
McpSdkServerConfig(
server=server, # Wrong key! SDK can't strip this
name="name" # Missing type="sdk"
)
Why it matters:
# SDK expects dict[str, McpSdkServerConfig | McpStdioServerConfig | ...]
options = ClaudeAgentOptions(
mcp_servers={
"server_name": create_sdk_mcp_server(
name="server_name",
version="1.0.0",
tools=[tool1, tool2]
)
}
)
When patching SDK bugs:
def patched_create_sdk_mcp_server(
name: str,
version: str = "1.0.0", # Bug: SDK passes this to Server() which doesn't accept it
tools: list[SdkMcpTool] | None = None,
) -> McpSdkServerConfig:
"""Patched version fixing bug #323."""
from mcp.server import Server
# FIX 1: Don't pass version to Server.__init__()
# Original SDK bug: Server(name, version=version)
server = Server(name) # Correct: Server only accepts name
# ... tool registration ...
# FIX 2: Return with correct TypedDict keys
# SDK subprocess_cli.py:154-159 expects these exact keys:
# - type="sdk" for identification
# - name for server name
# - instance for Server object (stripped before JSON serialization)
return McpSdkServerConfig(
type="sdk", # SDK checks config.get("type") == "sdk"
name=name, # Identifier
instance=server # SDK strips: k != "instance"
)
After fixing SDK bugs:
# 1. Verify immediate return
result = create_sdk_mcp_server(name="test", tools=[tool1])
assert result["type"] == "sdk"
assert result["name"] == "test"
assert "instance" in result
# 2. Verify SDK processing (simulate SDK's internal logic)
sdk_config = {k: v for k, v in result.items() if k != "instance"}
import json
json.dumps({"mcpServers": {"test": sdk_config}}) # Should not error
# 3. Test full workflow
options = ClaudeAgentOptions(mcp_servers={"test": result})
async with ClaudeSDKClient(options=options) as client:
# Should successfully connect without JSON serialization errors
pass
Symptom: Error occurs in SDK internal code, not at return statement
Cause: Wrong TypedDict keys - runtime doesn't validate, fails downstream
Solution: Read SDK source to find exact keys it expects
Symptom: Object of type X is not JSON serializable
Cause: SDK failed to strip non-serializable fields
Solution:
k != "instance")type="sdk")Symptom: TypeError: __init__() got unexpected keyword argument
Cause: SDK passes parameters that underlying library doesn't accept
Solution:
# Find error in logs
tail -50 logs/errors.log
# Find SDK source
find .venv/lib -name "*subprocess_cli*"
# Verify TypedDict structure
python -c "from claude_agent_sdk import McpSdkServerConfig; print(McpSdkServerConfig.__required_keys__)"
.quibbler/rules.md - "Check Full Error Tracebacks for SDK Failures"Use when transcribing audio files with speaker diarization. Triggers on TRANSCRIBE keyword.
Create, update, delete, and query Google Calendar events using gcallm CLI, MCP tools, or direct API calls.
Rule-based methodology for essay development. Load this index first, then load specific essay type file based on task.
Comprehensive guide for managing Claude Code snippets v2.0 - discovering locations, creating snippets from files, searching by name/pattern/description, and validating configurations. Use this skill when users want to create, search, or manage snippet configurations in their Claude Code environment. Updated for LLM-friendly interface with TTY auto-detection.
Style guide and primer for writing in Warren Zhu's voice. Use when drafting emails, essays, blog posts, technical documents, consulting deliverables, presentations, or any writing for or as Warren. Covers philosophical sensibilities, stylistic patterns, characteristic moves, tone calibration, and professional/technical writing registers. Also useful when understanding Warren's intellectual background and preferences for advising him.
Use when interacting with Harvard Canvas LMS - fetching courses, assignments, grades, submissions, modules, calendar events. Trigger with CANVAS keyword.