langflow-ai/langflow · warning · HTTPException

Metadata array entry under '{key}' exceeds {KB_METADATA_MAX_

Error message

Metadata array entry under '{key}' exceeds {KB_METADATA_MAX_VALUE_LENGTH} characters.

What it means

Each string entry inside a metadata array is individually subject to the 256-character KB_METADATA_MAX_VALUE_LENGTH cap. After the array passes its 16-item and all-strings checks, any single element longer than 256 characters rejects the field with 422 — the same rationale as the scalar cap: array entries are copied onto every chunk.

Source

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

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]:
    """Enforce the user-metadata contract on a decoded dict.

    Returns the same dict (a shallow copy is *not* made — callers may mutate
    safely once validation passes). Raises :class:`HTTPException` with a 422
    status on any violation so FastAPI surfaces an inline error.
    """
    if not isinstance(metadata, dict):
        msg = "Metadata must be a JSON object."
        raise HTTPException(status_code=422, detail=msg)
    if len(metadata) > KB_METADATA_MAX_KEYS:
        msg = f"Metadata exceeds the {KB_METADATA_MAX_KEYS} key limit."
        raise HTTPException(status_code=422, detail=msg)

View on GitHub (pinned to 976ec789d2)

Solutions

  1. Truncate each array entry to <=256 chars client-side.
  2. Reconsider what belongs in metadata: long excerpts belong in the ingested document text, not metadata arrays.
  3. Add a client-side assertion over all entries: max(map(len, arr)) <= 256.
  4. For long structured values, store an external reference id in the array and keep content elsewhere.

Example fix

# before
metadata = {"quotes": [paragraph_1, paragraph_2]}  # paragraphs > 256 chars

# after
MAX = 256
metadata = {"quotes": [q[:MAX] for q in quotes]}  # or drop quotes from metadata entirely
Defensive patterns

Strategy: validation

Validate before calling

from langflow.utils.kb_constants import KB_METADATA_MAX_VALUE_LENGTH as MAXV

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

Type guard

def array_entries_within_limit(v) -> bool:
    return not isinstance(v, list) or all(len(e) <= 256 for e in v)

Try / catch

try:
    validate_user_metadata(meta)
except HTTPException as e:
    if e.status_code == 422 and 'array entry' in e.detail and 'exceeds' in e.detail:
        meta = cap_array_entries(meta); validate_user_metadata(meta)
    else:
        raise

Prevention

When it happens

Trigger: metadata or per_file_metadata contains e.g. {"sections": ["intro", "<400-char paragraph>"]}. The array has <=16 entries and they are all strings, but one entry exceeds 256 characters, so this specific message fires after checks 147/148 passed.

Common situations: Chunking-like data (paragraphs, quotes, excerpts) mistakenly placed in tag arrays; keyword lists where one entry is a whole sentence; concatenated category paths ('a/b/c/.../z') grown unbounded over time.

Related errors

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