Investigation Memo on Claude Code API Error (Connection error.) When Using Virtual Machines

Overview

Target Audience: Those who have encountered connection errors while using Claude Code, especially those using virtualization tools on macOS.

This is a technical memo summarizing the investigation process of an API Error (Connection error.) encountered when first using Claude Code.

It focuses on the phenomenon that occurred when simultaneously using the virtualization tool "Tart" (a lightweight virtualization solution for macOS) on macOS, and documents a systematic investigation methodology and root cause analysis approach.

https://github.com/cirruslabs/tart

Environment

• OS: macOS Sequoia 15.5
• CPU: Apple M4 chip
• Memory: 32GB
• Storage: 1TB (sufficient free space)

Issue Encountered

Error Details

While using Claude Code, an API Error (Connection error.) occurred, making it temporarily unusable.

At the time of this error, it was confirmed that there were no issues with the account connection or other network connections.

When using the Anthropic API, HTTP error codes are typically output, but in this case, no clue could be extracted from the error message.

400 - invalid_request_error: There was an issue with the format or content of your request. We may also use this error type for other 4XX status codes not listed below.

401 - authentication_error: There’s an issue with your API key.

403 - permission_error: Your API key does not have permission to use the specified resource.

404 - not_found_error: The requested resource was not found.

413 - request_too_large: Request exceeds the maximum allowed number of bytes.

429 - rate_limit_error: Your account has hit a rate limit.

500 - api_error: An unexpected error has occurred internal to Anthropic’s systems.

529 - overloaded_error: Anthropic’s API is temporarily overloaded.

https://docs.anthropic.com/en/api/errors

Reproducibility

• Confirmed that the connection error reproduced when Tart was running.
• Confirmed that Claude Code worked normally when Tart was stopped.

First, I suspected a conflict between Tart and Claude Code as the likely cause and proceeded with the investigation.

Investigation and Analysis

I saw information that the issue was resolved by stopping Docker, so I started investigating from port conflicts and resource contention.

https://x.com/mwarger/status/1935875707051073666

The following investigation and analysis were conducted interactively with Claude Code and Gemini CLI.

Understanding the Current Network State

Firewall or VPN connection issues seemed irrelevant, so I skipped them this time.

https://support.anthropic.com/en/articles/10366432-i-m-getting-an-api-connection-error-how-can-i-fix-it

• Tart's Network Mode: Tart starts virtual machines in NAT (Network Address Translation) mode by default. In this mode, the virtual machine shares the host OS's IP address, and the host OS handles NAT.
• Claude Code Communication: Claude Code communicates with the Anthropic API via HTTPS (port 443).
• Process and Port Investigation:
  • Executed the lsof -i -P | grep tart command. No signs that the Tart process directly listens on network ports.
  • Used ps aux | grep -i tart to confirm the existence of Tart-related processes and their PIDs (Process IDs).
  • Ran lsof -i -P | grep <PID> again for the identified PIDs, but no direct occupation of network ports by those processes was confirmed.
  • The netstat -a command provided an overall view of active connections and listening ports, but no clear evidence of specific port conflicts caused by Tart was obtained.

Resource Consumption Relevance

• Claude Code is reported to exhibit high memory and CPU usage when processing large codebases or during prolonged use.

https://github.com/anthropics/claude-code/issues/2278

• Tart also consumes system resources to run virtual machines. If Claude Code starts while Tart is occupying resources, the overall system memory may become insufficient, potentially preventing Claude Code from maintaining a stable network connection.

Root Cause Analysis

Based on the investigation, three possibilities were identified. The rationale and verification results for each hypothesis are summarized.

Hypothesis 1: Network Layer Interference

Rationale: Conflict between Tart's NAT mode and Claude Code's HTTPS communication

• Virtual network interface created by Tart
• Impact on the host OS's network stack

Verification Result: No direct evidence of port conflicts was found. Additionally, cases were confirmed where Claude Code operated normally even while Tart was running, so this is unlikely to be the primary cause.

Hypothesis 2: System Resource Contention ⭐️Most Likely

Rationale: Instability when both tools are used simultaneously even with 32GB of memory

• Tart: Memory consumption due to virtual machine execution
• Claude Code: High memory usage when processing large codebases (known issue)

Verification Result: Matches the pattern where network connections become unstable when overall system memory is insufficient.

Hypothesis 3: API Concurrent Connection Limits

Rationale: Multiple sessions due to Claude Code's parallel processing

• Reported occurrences on both free and paid plans (GitHub Issue)
• Unnatural that a Connection error appears instead of a Rate limit error.

Verification Result: Since the details of Anthropic's limits are unknown, this remains a possibility.

https://support.anthropic.com/ja/articles/11014257-claudeの最大プラン使用量について

Countermeasures and Preventive Measures

Troubleshooting Flowchart

Step-by-step procedures to follow when a Claude Code connection error occurs:

🔄 Basic Checks

1. Confirm Network Connection

   • Verify that other web services are accessible normally
   • Check the stability of Wi-Fi/wired connection

2. Restart Claude Code

   • Terminate Claude Code with Ctrl+C
   • Restart the terminal and rerun Claude Code

⚙️ System Resource Check

3. Check Memory Usage

   # For macOS
   Check in Activity Monitor > Memory tab
   # Or
   top -l 1 | grep "PhysMem"
   

4. Optimize Claude Code Memory

   # Run inside Claude Code
   /compact
   

5. Stop Virtualization Tools

   # For Tart
   tart stop [VM name]
   # For Docker  
   docker stop $(docker ps -q)
   

🔧 Detailed Investigation

6. Investigate Processes and Ports

   # Check resource-intensive processes
   ps aux | head -20
   # Check network port usage
   lsof -i -P | grep LISTEN
   

💡 Advanced Countermeasures

7. Change Tart Network Settings (when using Tart)
   • Consider switching from NAT mode to Bridge mode
   • Refer to the official documentation

Short-term Countermeasures

• Stop Tart: By stopping Tart when using Claude Code, you can temporarily avoid the error.
• Monitor and Free Resources: Monitor memory usage in macOS's Activity Monitor and close other applications as needed to free up memory. Periodically running Claude Code's /compact command to reduce memory usage also seems effective.

https://docs.anthropic.com/ja/docs/claude-code/troubleshooting#パフォーマンスと安定性

Long-term Solutions

• Review Tart's Network Settings:
  • Consider changing Tart's network mode from NAT mode (Network Address Translation: a method of sharing the host OS's IP address) to a different setting (e.g., Bridge mode). In bridge mode, the virtual machine has its own IP address, which may reduce interference with the host OS's network.

https://tart.run/faq/#resolving-the-vms-ip-when-using-bridged-networking

(I also saw mentions of timeout errors when using WSL or IPv6 connections, but these might be different cases.)

https://www.reddit.com/r/ClaudeAI/comments/1jp6b24/claude_code_api_error_connection_error/

https://note.com/inataku_kuma/n/n770101719cd1

• Increase System Resources:
  • Consider upgrading your Mac's memory.
  • However, since the current model has 32GB of memory, it is generally sufficient for regular tasks.
• Optimize Usage Patterns:
  • Depending on your environment, you may need to adjust your workflow, such as avoiding simultaneous use of memory-intensive tools and Claude Code.
    • In this case, it was a somewhat special situation where AI agents were being tested in a virtualized environment.
  • Also consider the possibility of similar conflicts occurring when using other virtualization tools or memory-intensive applications.
    • Perhaps regularly monitor system resources (especially memory) and check for abnormal consumption?

Checklist for Similar Issues

As a reference if you encounter a similar connection error:

• Basic Check: Perform network connection check and restart Claude Code
• Memory Check: Check memory usage in Activity Monitor
• Virtualization Tools: Try stopping Docker, Tart, VirtualBox, etc.
• Process Investigation: Identify resource-intensive processes with ps aux
• Port Check: Investigate network port usage with lsof -i -P
• Claude Code Optimization: Reduce memory usage with the /compact command
• Network Settings: Consider changing the network mode of the virtualization tool

If the error is resolved, note which step was effective; it will be helpful if a similar issue occurs in the future.

Summary

I investigated Claude Code connection errors in macOS and virtual machine environments, focusing on possible causes related to resource contention with Tart and network interference.

After looking into various aspects, frankly speaking, I was unable to pinpoint a specific cause in this investigation.

Since I am a beginner with Claude Code, I would appreciate it if anyone with knowledge on this matter could provide information in the comments section.

Bonus

Since I didn't achieve any results, I'll share a Snake game that Claude Code built in a few minutes to gloss things over 🐍

That's all from the scene.