langchain-ai/deepagents · error · TypeError

context.{key} must be a string or null, got {type(value).__n

Error message

context.{key} must be a string or null, got {type(value).__name__}.

What it means

`_validate_context` enforces that each field in `_CONTEXT_STR_OR_NONE_FIELDS` is either a string or null in the operation's `context` object. Any other type raises a `TypeError` naming `context.<key>` and the offending type, before the offload operation payload is built.

Source

Thrown at libs/code/deepagents_code/offload_api.py:460

def _validate_context(context: dict[str, Any]) -> None:
    """Check the context fields the offload operation consumes.

    Only the listed keys are type-checked; unknown keys pass through so a
    newer client can keep talking to this server version.

    Args:
        context: The request's `context` object.

    Raises:
        TypeError: If a consumed field has the wrong type, naming the field.
    """
    for key in _CONTEXT_STR_OR_NONE_FIELDS:
        value = context.get(key)
        if value is not None and not isinstance(value, str):
            msg = f"context.{key} must be a string or null, got {type(value).__name__}."
            raise TypeError(msg)
    for key in _CONTEXT_DICT_FIELDS:
        value = context.get(key)
        if value is not None and not isinstance(value, dict):
            msg = f"context.{key} must be an object, got {type(value).__name__}."
            raise TypeError(msg)
    limit = context.get("model_context_limit")
    # bool is an int subclass, so exclude it explicitly: JSON `true` is not a
    # token limit.
    if limit is not None and (isinstance(limit, bool) or not isinstance(limit, int)):
        msg = (
            "context.model_context_limit must be an integer or null, "
            f"got {type(limit).__name__}."
        )
        raise TypeError(msg)
    auto_approve = context.get("auto_approve")
    if auto_approve is not None and not isinstance(auto_approve, bool):
        msg = (
            f"context.auto_approve must be a boolean or null, "

View on GitHub (pinned to a1af029e6e)

Solutions

1. Pass the field as a string: `"summarization_model": "gpt-4o-mini"`, or omit/null it
2. Convert at the boundary with `str(value)` when the value is known to be name-like
3. Validate the context dict before calling the API

Example fix

// before
context = {"summarization_model": 4}
// after
context = {"summarization_model": str(4) if not isinstance(4, str) else 4}

for k in ("summarization_model",):
    v = context.get(k)
    if v is not None and not isinstance(v, str):
        raise TypeError(f"context.{k} must be a string or null")

def is_str_or_none(v: object) -> TypeGuard[str | None]:
    return v is None or isinstance(v, str)

try:
    payload = _operation_payload(op, context)
except TypeError as e:
    logging.error("invalid context: %s", e)
    raise

When it happens

Trigger: Calling an offload API operation with `context={..., "summarization_model": 42}` (or a list/bool) where a string-or-null field is expected, e.g. a numeric model name or an unconverted config value.

Common situations: JSON/YAML config with the model id accidentally as a number; passing a Python object instead of its string repr; deserialization producing ints where strings are required.

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

• context.{key} must be an object, got {type(value).__name__}.
• interpreter_ptc must be False, 'safe', 'all', or a list of t
• max_retries must be an int, got {type(max_retries).__name__}
• stream_output_is_visible must be a bool, got {type(stream_ou
• context.model_context_limit must be an integer or null, got

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