From the Inside Claude Code: The Claude Code Ecosystem architecture map

Every SDK module imports its exceptions from one file, _errors.py

risk · high · verified

The exception hierarchy in _errors.py (ClaudeSDKError, CLIConnectionError, CLINotFoundError, ProcessError, ResultError, CLIJSONDecodeError, MessageParseError) is imported directly by the CLI transport, ClaudeSDKClient, the control protocol query, the message parser and the package entry point. None has a fallback. A breaking change to this file reaches all five, and through the transport it reaches the internal client that drives one-shot queries.

Impact: Renaming or reshaping an exception breaks the public exports and every place that catches or raises it, so callers lose their error handling at once.

Recommendation (small effort): Treat _errors.py as a frozen public contract: add new exception classes as subclasses and keep existing names and constructor arguments stable. Cover the hierarchy with a test that imports every name the package entry point re-exports.

The trail

  1. Errors
  2. Subprocess CLI Transport
  3. Internal Client
  4. ClaudeSDKClient
  5. Control Protocol Query
  6. Message Parser
  7. Package Exports
Open on the map

More from this board

© 2026 Syntaxia App Platform Ltd.

Syntaxia App Platform Ltd. Registered in England and Wales, company no. 15272701 Registered office: 3rd Floor, 86–90 Paul Street, London EC2A 4NE, United Kingdom contact@provenmap.com