langchain-ai/deepagents · error · ValueError

External event correlation_id must be a string when present

Error message

External event correlation_id must be a string when present

What it means

`correlation_id` is an optional string used to tie related external events together. `decode_external_event` allows it to be absent or null but rejects any other type (number, bool, object, array) with a `ValueError`. This keeps downstream correlation logic working with a consistent string type.

Source

Thrown at libs/code/deepagents_code/event_bus.py:403

        msg = f"External event kind must be one of {sorted(_VALID_KINDS)}; got {kind!r}"
        raise ValueError(msg)

    payload = raw.get("payload")
    if not isinstance(payload, str) or not payload.strip():
        msg = "External event payload must be a non-empty string"
        raise ValueError(msg)

    bypass = raw.get("bypass", BypassTier.QUEUED.value)
    try:
        bypass_tier = BypassTier(bypass)
    except ValueError as exc:
        msg = f"External event bypass must be a valid bypass tier: {exc}"
        raise ValueError(msg) from exc

    correlation_id = raw.get("correlation_id")
    if correlation_id is not None and not isinstance(correlation_id, str):
        msg = "External event correlation_id must be a string when present"
        raise ValueError(msg)

    return ExternalEvent(
        kind=kind,
        payload=payload,
        source=source,
        bypass=bypass_tier,
        correlation_id=correlation_id,
    )

View on GitHub (pinned to a1af029e6e)

Solutions

1. Serialize the correlation id as a string, e.g. `str(uuid.uuid4())`.
2. Omit `correlation_id` entirely when no correlation is needed.
3. Coerce numeric IDs to strings on the producer side.
4. Catch `ValueError` in reader diagnostics to flag producers sending typed ids.

Example fix

// before
{"kind":"noop","payload":"x","correlation_id":12345}

// after
{"kind":"noop","payload":"x","correlation_id":"12345"}

def assert_correlation_id_ok(value) -> None:
    if value is not None and not isinstance(value, str):
        raise ValueError("correlation_id must be a string when present")

def is_valid_correlation_id(value) -> bool:
    return value is None or isinstance(value, str)

try:
    event = decode_external_event(data, source=source)
except ValueError as exc:
    logger.warning("external event rejected (correlation_id): %s", exc)
    return None

When it happens

Trigger: Sending `"correlation_id":12345`, a UUID object serialized as a JSON object, a boolean, or a nested value instead of a string (or null/omitted).

Common situations: Producers using auto-increment integer IDs; UUID libraries serializing to objects instead of `str(uuid)`; shell scripts interpolating raw numbers without quotes.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• External event must be valid JSON: {exc.msg}
• External event kind must be one of {sorted(_VALID_KINDS)}; g
• External event bypass must be a valid bypass tier: {exc}
• Invalid {SERVER_ENV_PREFIX}ALLOW_FS_TOOLS value: {raw!r}; ex
• Invalid MCP config at {mcp_config_path}: {exc}

AI-assisted analysis of langchain-ai/deepagents@a1af029e6e (2026-08-29). Data as JSON: /api/errors/ff52dec1ddd0850e. Report an issue: GitHub.