{"record":{"id":"8ea354e7863fb8bb","repo":"langflow-ai/langflow","slug":"metadata-value-for-key-exceeds-kb-metadata-ma","errorCode":null,"errorMessage":"Metadata value for '{key}' exceeds {KB_METADATA_MAX_VALUE_LENGTH} characters.","messagePattern":"Metadata value for '(.+?)' exceeds (.+?) characters\\.","errorType":"validation","errorClass":"HTTPException","httpStatus":422,"severity":"warning","filePath":"src/backend/base/langflow/api/utils/kb_metadata.py","lineNumber":48,"sourceCode":"    KB_METADATA_RESERVED_KEYS,\n)\n\n_KEY_ALLOWED_CHARS = set(\"abcdefghijklmnopqrstuvwxyz0123456789_\")\n\n\ndef _is_valid_key(key: str) -> bool:\n    if not key or len(key) > KB_METADATA_MAX_KEY_LENGTH:\n        return False\n    return all(c in _KEY_ALLOWED_CHARS for c in key)\n\n\ndef _validate_value(key: str, value: Any) -> None:\n    if isinstance(value, (bool, int, float)):\n        return\n    if isinstance(value, str):\n        if len(value) > KB_METADATA_MAX_VALUE_LENGTH:\n            msg = f\"Metadata value for '{key}' exceeds {KB_METADATA_MAX_VALUE_LENGTH} characters.\"\n            raise HTTPException(status_code=422, detail=msg)\n        return\n    if isinstance(value, list):\n        if len(value) > KB_METADATA_MAX_ARRAY_LENGTH:\n            msg = f\"Metadata array '{key}' exceeds {KB_METADATA_MAX_ARRAY_LENGTH} items.\"\n            raise HTTPException(status_code=422, detail=msg)\n        for entry in value:\n            if not isinstance(entry, str):\n                msg = f\"Metadata array '{key}' must contain only strings.\"\n                raise HTTPException(status_code=422, detail=msg)\n            if len(entry) > KB_METADATA_MAX_VALUE_LENGTH:\n                msg = f\"Metadata array entry under '{key}' exceeds {KB_METADATA_MAX_VALUE_LENGTH} characters.\"\n                raise HTTPException(status_code=422, detail=msg)\n        return\n    msg = f\"Metadata value for '{key}' must be a string, number, bool, or string array; got {type(value).__name__}.\"\n    raise HTTPException(status_code=422, detail=msg)\n\n\ndef validate_user_metadata(metadata: dict[str, Any]) -> dict[str, Any]:","sourceCodeStart":30,"sourceCodeEnd":66,"githubUrl":"https://github.com/langflow-ai/langflow/blob/976ec789d2886a86de109c044d089d68e96c9a35/src/backend/base/langflow/api/utils/kb_metadata.py#L30-L66","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Truncate or drop the oversized value client-side to <=256 characters before submitting.","Move long text into the document body / a KB description field instead of chunk metadata — metadata is for filtering, not content.","If your payloads are structurally long (e.g. lists of long strings), split them or store a reference/id in metadata.","Do not raise the constant KB_METADATA_MAX_VALUE_LENGTH without measuring your vector store's per-document limit (see kb_constants.py comment)."],"exampleFix":"# before\nmetadata = {\"summary\": full_text}  # full_text is 3000 chars -> 422\n\n# after\nMAX = 256\nmetadata = {\"summary\": full_text[:MAX], \"summary_ref\": store(full_text)}","handlingStrategy":"validation","validationCode":"from langflow.utils.kb_constants import KB_METADATA_MAX_VALUE_LENGTH as MAXV\n\ndef clean_metadata(meta: dict) -> dict:\n    return {k: (v[:MAXV] if isinstance(v, str) else v) for k, v in meta.items()}","typeGuard":"def is_valid_value(v) -> bool:\n    return not (isinstance(v, str) and len(v) > 256)","tryCatchPattern":"try:\n    validate_user_metadata(meta)\nexcept HTTPException as e:\n    if e.status_code == 422 and 'exceeds' in e.detail and 'characters' in e.detail:\n        meta = truncate_strings(meta, 256); validate_user_metadata(meta)\n    else:\n        raise","preventionTips":["Import the KB_METADATA_* constants from langflow.utils.kb_constants instead of hardcoding caps.","Keep metadata filter-oriented (ids, tags, enums), not content-carrying.","Truncate generated fields (summaries, URLs) before submission."],"tags":["knowledge-base","metadata","validation","http-422","limits"],"backgroundTag":null,"analyzedSha":"976ec789d2886a86de109c044d089d68e96c9a35","analyzedAt":"2026-08-14T18:23:12.227Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}