langchain-ai/deepagents · error · ValueError

`max_snapshot_bytes` must be >= 1 or None

Error message

`max_snapshot_bytes` must be >= 1 or None

What it means

The REPL middleware validates at construction that `max_snapshot_bytes` is `None` or an integer >= 1, because a zero/negative snapshot size cap is meaningless. Invalid values raise `ValueError` immediately in `__init__`.

Source

Thrown at libs/partners/quickjs/langchain_quickjs/middleware.py:263

        timeout: float = _DEFAULT_TIMEOUT,
        max_ptc_calls: int | None = _DEFAULT_MAX_PTC_CALLS,
        tool_name: str = _DEFAULT_TOOL_NAME,
        max_result_chars: int = _DEFAULT_MAX_RESULT_CHARS,
        capture_console: bool = True,
        subagents: bool = True,
        ptc: PTCOption | None = None,
        mode: PersistenceMode | None = None,
        max_snapshot_bytes: int | None = None,
        snapshot_signing_key: str | bytes | None = None,
    ) -> None:
        """Initialize REPL middleware state and build the exposed eval tool."""
        super().__init__()
        if max_ptc_calls is not None and max_ptc_calls < 1:
            msg = "`max_ptc_calls` must be >= 1 or None"
            raise ValueError(msg)
        if max_snapshot_bytes is not None and max_snapshot_bytes < 1:
            msg = "`max_snapshot_bytes` must be >= 1 or None"
            raise ValueError(msg)
        self._memory_limit = memory_limit
        self._timeout = timeout
        self._max_ptc_calls = max_ptc_calls
        self._tool_name = tool_name
        self._max_result_chars = max_result_chars
        self._capture_console = capture_console
        self._subagents = subagents
        self._ptc = ptc
        self._mode = _resolve_mode(mode=mode)
        self._max_snapshot_bytes = (
            memory_limit if max_snapshot_bytes is None else max_snapshot_bytes
        )
        self._snapshot_signing_key = (
            normalize_signing_key(snapshot_signing_key)
            if snapshot_signing_key is not None
            else None
        )
        self._registry = _Registry(

View on GitHub (pinned to a1af029e6e)

Solutions

1. Pass `max_snapshot_bytes=None` to use the default behavior, not 0.
2. Set a positive byte cap (>= 1) if you want to limit snapshot sizes.
3. Coerce empty/missing env values to None rather than 0.

Example fix

// before
QuickJsMiddleware(max_snapshot_bytes=int(os.environ.get("MAX_SNAPSHOT_BYTES", 0)))

// after
raw = os.environ.get("MAX_SNAPSHOT_BYTES")
QuickJsMiddleware(max_snapshot_bytes=int(raw) if raw else None)

if max_snapshot_bytes is not None and max_snapshot_bytes < 1:
    raise ValueError("max_snapshot_bytes must be >= 1 or None")

def is_valid_byte_cap(v) -> bool:
    return v is None or (isinstance(v, int) and not isinstance(v, bool) and v >= 1)

try:
    mw = QuickJsMiddleware(max_snapshot_bytes=max_snapshot_bytes)
except ValueError as e:
    if "max_snapshot_bytes" in str(e):
        mw = QuickJsMiddleware(max_snapshot_bytes=None)

When it happens

Trigger: `QuickJsMiddleware(max_snapshot_bytes=0)` or a negative value, commonly from `int(os.environ.get("MAX_SNAPSHOT", 0))` or a config default of 0.

Common situations: Trying to 'disable' snapshots with 0 instead of None; unset env vars coerced to 0; unit-test fixtures that pass 0 by mistake.

Understand the failure class

Background: "Invalid configuration value" and "Unsupported/Unknown setting value" errors: why libraries reject your config strings, numbers, and types — this error's family across 30 libraries.

Related errors

• `snapshot_signing_key` must be a non-empty str or bytes.
• `mode` must be one of 'thread', 'turn', or 'call'.
• `max_ptc_calls` must be >= 1 or None
• {what} must be absolute: {path}
• Home directory is not absolute: {launch_home}. Set $HOME to

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