langflow-ai/langflow · warning · HTTPException

Metadata value for ' ' exceeds characters.

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.

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.

Appendix: 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)