langflow-ai/langflow · warning · HTTPException

Metadata array '{key}' exceeds {KB_METADATA_MAX_ARRAY_LENGTH

Error message

Metadata array '{key}' exceeds {KB_METADATA_MAX_ARRAY_LENGTH} items.

What it means

Metadata validation caps list-valued metadata at KB_METADATA_MAX_ARRAY_LENGTH = 16 items. Arrays are allowed only as lists of short strings; a longer list is rejected with 422 because array metadata is replicated onto every chunk of the ingested file, multiplying storage in the vector store.

Source

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

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]:
    """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.

View on GitHub (pinned to 976ec789d2)

Solutions

Keep any single array <=16 items — take the top-N tags (e.g. by score/frequency) client-side.
Split an oversized tag list into multiple metadata keys (tags_1, tags_2, ...) if truly needed — still respecting the 16-key overall limit.
If more tags are genuinely required, store them in your own index keyed by file id and keep only coarse tags in KB metadata.
Check KB_METADATA_MAX_ARRAY_LENGTH in langflow.utils.kb_constants before submitting so the client and server agree.

Example fix

# before
metadata = {"tags": all_tags}  # 40 tags -> 422

# after
MAX_ARRAY = 16
metadata = {"tags": sorted(all_tags, key=score, reverse=True)[:MAX_ARRAY]}

Defensive patterns

Strategy: validation

Validate before calling

from langflow.utils.kb_constants import KB_METADATA_MAX_ARRAY_LENGTH as MAXA

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

Type guard

def is_valid_array(v) -> bool:
    return not isinstance(v, list) or len(v) <= 16

Try / catch

try:
    validate_user_metadata(meta)
except HTTPException as e:
    if e.status_code == 422 and 'exceeds' in e.detail and 'items' in e.detail:
        meta = {k: (v[:16] if isinstance(v, list) else v) for k, v in meta.items()}
        validate_user_metadata(meta)
    else:
        raise

Prevention

Take top-N tags client-side rather than shipping full taxonomies.
Split very long lists across multiple keys only if the 16-key cap allows.
Re-check array lengths whenever a taxonomy grows.

When it happens

Trigger: A multipart ingest request where the metadata JSON contains an array with 17+ entries, e.g. {"tags": ["a","b",... 20 items]}, either at run level (metadata field) or inside per_file_metadata. The length check runs before per-entry type/length checks, so an oversize array of valid strings still fails here first.

Common situations: Tag/category taxonomies imported from another system with dozens of labels per document; keyword extraction pipelines emitting unbounded tag lists; teams expecting tags to scale like a documents table rather than per-chunk metadata.

Related errors

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