langflow-ai/langflow · warning · HTTPException

Metadata value for '{key}' exceeds {KB_METADATA_MAX_VALUE_LE

Error message

Metadata value for '{key}' exceeds {KB_METADATA_MAX_VALUE_LENGTH} characters.

What it means

Knowledge-base metadata validation (_validate_value in kb_metadata.py) enforces a 256-character cap (KB_METADATA_MAX_VALUE_LENGTH) on any single string metadata value submitted during KB ingestion. Vector stores have per-document size ceilings, and uncapped metadata would let one request inflate every chunk, so oversize strings are rejected with 422 before ingestion starts.

Source

Thrown at src/backend/base/langflow/api/utils/kb_metadata.py:48

    KB_METADATA_RESERVED_KEYS,
)

_KEY_ALLOWED_CHARS = set("abcdefghijklmnopqrstuvwxyz0123456789_")


def _is_valid_key(key: str) -> bool:
    if not key or len(key) > KB_METADATA_MAX_KEY_LENGTH:
        return False
    return all(c in _KEY_ALLOWED_CHARS for c in key)


def _validate_value(key: str, value: Any) -> None:
    if isinstance(value, (bool, int, float)):
        return
    if isinstance(value, str):
        if len(value) > KB_METADATA_MAX_VALUE_LENGTH:
            msg = f"Metadata value for '{key}' exceeds {KB_METADATA_MAX_VALUE_LENGTH} characters."
            raise HTTPException(status_code=422, detail=msg)
        return
    if isinstance(value, list):
        if len(value) > KB_METADATA_MAX_ARRAY_LENGTH:
            msg = f"Metadata array '{key}' exceeds {KB_METADATA_MAX_ARRAY_LENGTH} items."
            raise HTTPException(status_code=422, detail=msg)
        for entry in value:
            if not isinstance(entry, str):
                msg = f"Metadata array '{key}' must contain only strings."
                raise HTTPException(status_code=422, detail=msg)
            if len(entry) > KB_METADATA_MAX_VALUE_LENGTH:
                msg = f"Metadata array entry under '{key}' exceeds {KB_METADATA_MAX_VALUE_LENGTH} characters."
                raise HTTPException(status_code=422, detail=msg)
        return
    msg = f"Metadata value for '{key}' must be a string, number, bool, or string array; got {type(value).__name__}."
    raise HTTPException(status_code=422, detail=msg)


def validate_user_metadata(metadata: dict[str, Any]) -> dict[str, Any]:

View on GitHub (pinned to 976ec789d2)

Solutions

  1. Truncate or drop the oversized value client-side to <=256 characters before submitting.
  2. Move long text into the document body / a KB description field instead of chunk metadata — metadata is for filtering, not content.
  3. If your payloads are structurally long (e.g. lists of long strings), split them or store a reference/id in metadata.
  4. Do not raise the constant KB_METADATA_MAX_VALUE_LENGTH without measuring your vector store's per-document limit (see kb_constants.py comment).

Example fix

# before
metadata = {"summary": full_text}  # full_text is 3000 chars -> 422

# after
MAX = 256
metadata = {"summary": full_text[:MAX], "summary_ref": store(full_text)}
Defensive patterns

Strategy: validation

Validate before calling

from langflow.utils.kb_constants import KB_METADATA_MAX_VALUE_LENGTH as MAXV

def clean_metadata(meta: dict) -> dict:
    return {k: (v[:MAXV] if isinstance(v, str) else v) for k, v in meta.items()}

Type guard

def is_valid_value(v) -> bool:
    return not (isinstance(v, str) and len(v) > 256)

Try / catch

try:
    validate_user_metadata(meta)
except HTTPException as e:
    if e.status_code == 422 and 'exceeds' in e.detail and 'characters' in e.detail:
        meta = truncate_strings(meta, 256); validate_user_metadata(meta)
    else:
        raise

Prevention

When it happens

Trigger: POSTing a multipart ingest request whose `metadata` form field (JSON) contains a string value longer than 256 chars, e.g. {"summary": "<300 chars>"}; or a per_file_metadata inner dict with the same. The limit counts Python string length (characters), not bytes.

Common situations: Stuffing a whole document abstract, a URL with a huge query string, a base64 blob, or an auto-generated description into metadata; scripts migrating existing keyword-tag payloads into KB metadata without truncation; LLM-generated metadata fields that are unbounded in length.

Related errors

AI-assisted analysis of langflow-ai/langflow@976ec789d2 (2026-08-14). Data as JSON: /api/errors/8ea354e7863fb8bb. Report an issue: GitHub.