API Connection Errors During Operation in WSL2 (Correlated with IP Changes)

API Connection Error Report

Issue Summary

Repeated "Connection error" API failures during Claude Code operation in WSL2 environment, causing work disruptions and timeouts.

Environment

• OS: WSL2 Ubuntu on Windows 10 Pro (Build 19045)
• Kernel: 6.6.87.2-microsoft-standard-WSL2
• Claude Code Version: Latest (as of 2026-01-28)
• Model: Claude Sonnet 4.5 (claude-sonnet-4-5-20250929)
• Network: WSL2 with dynamic IP (current: 172.22.77.61)

Error Pattern

Occurrence Timeline

1. First failure: After 9m 22s of work ("Churned for 9m 22s")

• Error: "API Error: Connection error."
• PostToolUse:Bash hook succeeded before error

1. Second failure: After 3m 57s of resumed work ("Worked for 3m 57s")

• Error: "API Error: Connection error."
• UserPromptSubmit hook succeeded before error

1. Third failure: After 3m 23s of resumed work ("Baked for 3m 23s")

• Error: "API Error: Connection error."
• UserPromptSubmit hook succeeded before error

Pattern Analysis

• Errors occur during active API operations, not at startup
• Hook execution succeeds, but subsequent API call fails
• Decreasing time between failures (9m → 4m → 3m)
• No network change detected on WSL2 side
• OAuth authentication NOT involved (different from Issue #20756)

Impact

Work Disruption

• Total disrupted time: 16+ minutes across 3 failures
• Pattern: Unpredictable mid-operation failures
• User action required: Manual "continue" after each failure
• Work loss: Context and progress potentially lost on each failure

Difference from Issue #20756

• #20756: OAuth authentication flow broken (login fails)
• This issue: API calls fail mid-operation (authentication already succeeded)
• #20756: Reproducible at startup
• This issue: Intermittent during operation

Expected Behavior

• API calls should complete successfully or return meaningful errors
• Connection errors should include diagnostic information
• Automatic retry with exponential backoff
• Graceful degradation with user notification

Actual Behavior

• Generic "Connection error" with no details
• Immediate failure, no retry attempted
• Work progress lost, manual intervention required
• No diagnostic information for troubleshooting

Reproduction Steps

1. Start Claude Code in WSL2 environment
2. Perform extended operation (5-10 minutes)
3. Observe intermittent "API Error: Connection error."
4. Note: Error may not occur on first attempt, appears intermittent

System Context

Related Issue

• Issue #20756: OAuth Authentication Broken in WSL2
• URL: https://github.com/anthropics/claude-code/issues/20756
• Status: OPEN, submitted 2026-01-25
• Different symptom (OAuth vs API call failure)

Project Context

Currently developing "API Connection Error Auto-Recovery System" when this error occurred - ironically validating the need for such a system.

WSL2 Configuration

• systemd enabled (/etc/wsl.conf)
• Port forwarding configured for OAuth (8080 → WSL2 IP)
• Network connectivity: stable (no IP changes during errors)

Diagnostic Information

Network Status (at time of error)

# WSL2 IP stable
ip addr show eth0 | grep inet
# 172.22.77.61/20

# Port forwarding active
netsh interface portproxy show v4tov4
# 8080 → 172.22.77.61

# Internet connectivity verified
curl -I https://api.anthropic.com
# (timing out - may indicate API-side issue)

Process Status

# Claude Code processes normal
ps aux | grep claude-code | wc -l
# <10 processes

# No zombie processes
ps aux | grep defunct | wc -l
# 0

Requested Actions

1. Investigate API connection stability in WSL2 environments
2. Provide detailed error messages (not just "Connection error")
3. Implement automatic retry with exponential backoff
4. Add connection diagnostics to error output
5. Document WSL2-specific considerations for API connectivity

Workaround

Currently no workaround available - user must manually continue after each failure and hope for success.

Priority

HIGH - Blocks productive work, requires constant manual intervention

---

Reported by: 이종철 (Jyong Chul Lee)
Contact: jyongchul@naver.com
Date: 2026-01-28
Related: Issue #20756 (OAuth authentication failure)

CRITICAL UPDATE (2026-01-28 18:28 KST)

WSL2 IP Address Changed During Session

• Before errors: 172.22.77.61 (referenced in initial report)
• After errors: 172.22.77.64 (current)
• Timing: IP changed between error occurrences and investigation

Root Cause Hypothesis

WSL2 IP address change may have triggered API connection failures:

1. Port forwarding configuration stale (still points to .61)
2. Active connections interrupted by IP change
3. Claude Code may cache WSL2 IP and fail on subsequent calls

Validation Needed

• Check if port forwarding auto-updates on IP change
• Test if API errors correlate with WSL2 restarts/IP changes
• Verify if Claude Code handles WSL2 dynamic IPs correctly

This finding strengthens the case for automatic IP monitoring and port forwarding updates in the recovery system being developed.