[BUG] claude-agent-sdk: MessageParseError on rate_limit_event message type

Bug Description

claude-agent-sdk's message_parser.py does not handle the rate_limit_event message type emitted by Claude Code CLI. This causes MessageParseError("Unknown message type: rate_limit_event") to be raised, which terminates the entire message stream.

Reproduction

Use claude-agent-sdk (tested on v0.1.37) to query Claude Code CLI
When rate limiting occurs, the CLI emits a message with "type": "rate_limit_event"
parse_message() in _internal/message_parser.py raises MessageParseError at the case _: branch (line 179-180)
The async generator in _internal/client.py (line 141) propagates the exception, terminating the stream

Root Cause

In _internal/message_parser.py, the parse_message function handles these types: user, assistant, system, result, stream_event. The rate_limit_event type is not included.

Notably, types.py already defines "rate_limit" as a known SystemMessageSubtype (line 635), suggesting awareness of this message category, but the parser lacks a corresponding case.

Expected Behavior

rate_limit_event messages should be parsed into a typed message object (e.g., SystemMessage) or at minimum be silently skipped rather than raising an exception that breaks the stream.

Workaround

Monkey-patching parse_message to catch the exception and return None:

import claude_agent_sdk._internal.client as _sdk_client
import claude_agent_sdk._internal.message_parser as _sdk_parser

_original_parse_message = _sdk_parser.parse_message

def _safe_parse_message(data):
    try:
        return _original_parse_message(data)
    except Exception:
        return None

_sdk_parser.parse_message = _safe_parse_message
_sdk_client.parse_message = _safe_parse_message

Environment

claude-agent-sdk: 0.1.37
claude-code CLI: latest (as of 2026-02-18)
OS: macOS

Suggested Fix

Looking at the code, here are two possible approaches:

Option A: Handle `rate_limit_event` explicitly

In _internal/message_parser.py, add a case before the case _: branch. Since "rate_limit" is already defined as a SystemMessageSubtype in types.py (line 635), it could be mapped to a SystemMessage:

        case "rate_limit_event":
            return SystemMessage(
                subtype="rate_limit",
                data=data,
            )

Option B: Make unknown types non-fatal

Change the case _: branch to log a warning instead of raising, so that future unknown message types don't break the stream:

        case _:
            logger.warning("Skipping unknown message type: %s", message_type)
            return None  # caller would need to filter None values

Option A is more precise, but Option B is more resilient against future CLI output changes. A combination of both might be ideal.

Either way, the key issue is that an informational message from the CLI should never terminate the entire stream via an exception.

I just downgraded to version 2.1.34 and it's working again:
npm install -g @anthropic-ai/claude-code@2.1.34

Question what were you working on to find this bug?

I was building a personal automation system on top of claude-agent-sdk. The latest version was required due to some other dependency constraint, so downgrading wasn't an option — which is why I ended up digging into the source.

I just ran in to the same problem using the python SDK version 0.1.39. I downgraded to 0.1.37 and it works.

The SDK's parse_message function doesn't seem to handle this message type and raises.

Here is my code:

import asyncio
from claude_agent_sdk import query

async def main():
    async for message in query(prompt="Write me a hello world haiku"):
        print(message)

asyncio.run(main())

Error:

  File ".venv/lib/python3.13/site-packages/claude_agent_sdk/_internal/client.py", line 141, in process_query
    yield parse_message(data)
          ~~~~~~~~~~~~~^^^^^^
  File ".venv/lib/python3.13/site-packages/claude_agent_sdk/_internal/message_parser.py", line 180, in parse_message
    raise MessageParseError(f"Unknown message type: {message_type}", data)
claude_agent_sdk._errors.MessageParseError: Unknown message type: rate_limit_event

That's what I thought so am I.

Closing for now — inactive for too long. Please open a new issue if this is still relevant.

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.

Navigation Menu

Repository navigation

[BUG] claude-agent-sdk: MessageParseError on rate_limit_event message type #26498

Bug Description

Reproduction

Root Cause

Expected Behavior

Workaround

Environment

Suggested Fix

Option A: Handle `rate_limit_event` explicitly

Option B: Make unknown types non-fatal

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

[BUG] claude-agent-sdk: MessageParseError on rate_limit_event message type #26498

Description

Bug Description

Reproduction

Root Cause

Expected Behavior

Workaround

Environment

Activity

42tahara commented on Feb 18, 2026

Suggested Fix

Option A: Handle rate_limit_event explicitly

Option B: Make unknown types non-fatal

ggimenes commented on Feb 19, 2026

richardwhiteii commented on Feb 20, 2026

42tahara commented on Feb 21, 2026

jakesco commented on Feb 21, 2026

richardwhiteii commented on Feb 22, 2026

github-actions commented on Mar 22, 2026

github-actions commented on Mar 31, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

Option A: Handle `rate_limit_event` explicitly