MemPalace/mempalace · error · ValueError

{field_name} is {size} bytes; maximum is {max_bytes} bytes

Error message

{field_name} is {size} bytes; maximum is {max_bytes} bytes

What it means

The UTF-8 encoding of the event body exceeds max_body_bytes (default 256 KiB, configurable via the Logstream constructor). The logstream never truncates payloads silently — the design contract is verbatim storage with explicit size errors — so oversized bodies raise instead. The check runs after surrogate stripping, on the actual byte length.

Source

Thrown at mempalace/logstream.py:152

        return None
    if not isinstance(value, str) or value not in EVENT_STATUSES:
        allowed = ", ".join(sorted(EVENT_STATUSES))
        raise ValueError(f"status={value!r} is not one of: {allowed}")
    return value


def _sanitize_body(value, max_bytes: int, field_name: str = "body") -> str:
    """Validate verbatim payload text. Empty is allowed; ``None`` becomes ''."""
    if value is None:
        return ""
    if not isinstance(value, str):
        raise ValueError(f"{field_name} must be a string")
    if "\x00" in value:
        raise ValueError(f"{field_name} contains null bytes")
    value = strip_lone_surrogates(value)
    size = len(value.encode("utf-8"))
    if size > max_bytes:
        raise ValueError(f"{field_name} is {size} bytes; maximum is {max_bytes} bytes")
    return value


def _sanitize_metadata(value) -> str:
    """Validate optional metadata dict and return its canonical JSON text."""
    if value is None:
        return "{}"
    if not isinstance(value, dict):
        raise ValueError("metadata must be an object")
    try:
        encoded = json.dumps(value, ensure_ascii=False, sort_keys=True)
    except (TypeError, ValueError) as exc:
        raise ValueError(f"metadata is not JSON-serializable: {exc}") from None
    if len(encoded.encode("utf-8")) > MAX_METADATA_BYTES:
        raise ValueError(f"metadata exceeds maximum size of {MAX_METADATA_BYTES} bytes")
    return encoded

View on GitHub (pinned to 06cb6987f0)

Solutions

1. Split the payload across multiple events (e.g. task.request chunks) or attach a stored artifact via put_artifact and reference its id in artifact_ids.
2. Check size first: if len(body.encode('utf-8')) > ls.max_body_bytes: ... before calling.
3. If large bodies are legitimate, raise the limit explicitly in the Logstream(db_path=..., max_body_bytes=...) constructor on every replica.

Example fix

// before
evt = ls.append_event(type="log.dump", body=huge_log_text, ...)
// after
art = ls.put_artifact(kind="log", content=huge_log_text, created_by="mac-codex")
evt = ls.append_event(type="log.dump", body="see artifact", artifact_ids=[art["id"]], ...)

def fits_body(ls, body: str) -> bool:
    return isinstance(body, str) and len(body.encode("utf-8")) <= ls.max_body_bytes

if not fits_body(ls, body):
    art = ls.put_artifact(kind="note", content=body, created_by=from_agent)
    body, artifact_ids = "see artifact", [art["id"]]

def body_within_limit(ls, body) -> bool:
    return body is None or (isinstance(body, str) and len(body.encode("utf-8")) <= ls.max_body_bytes)

try:
    evt = ls.append_event(..., body=body)
except ValueError as e:
    if "maximum is" in str(e) and "bytes" in str(e):
        art = ls.put_artifact(kind="note", content=body, created_by=from_agent)
        evt = ls.append_event(..., body="see artifact", artifact_ids=[art["id"]])
    else:
        raise

When it happens

Trigger: append_event with a body over 262,144 bytes by default; multi-byte UTF-8 content (CJK, emoji) whose byte length exceeds the cap even when under it in characters; callers who raised max_body_bytes on one replica but not another.

Common situations: Pasting whole log files or stack traces into an event body; agents forwarding full conversation transcripts as bodies; a config change lowering the limit while old producers still send large payloads.

Related errors

• {field_name} must be a string
• metadata exceeds maximum size of {MAX_METADATA_BYTES} bytes
• content is {len(raw)} bytes; maximum is {self.max_artifact_b
• {field_name} must be a non-empty string
• {field_name} exceeds maximum length of {_MAX_ROUTING_LENGTH}

AI-assisted analysis of MemPalace/mempalace@06cb6987f0 (2026-08-15). Data as JSON: /api/errors/d7024e5578aa7282. Report an issue: GitHub.