{"record":{"id":"a91238dc1be3bc63","repo":"langflow-ai/langflow","slug":"metadata-array-entry-under-key-exceeds-kb-met","errorCode":null,"errorMessage":"Metadata array entry under '{key}' exceeds {KB_METADATA_MAX_VALUE_LENGTH} characters.","messagePattern":"Metadata array entry under '(.+?)' exceeds (.+?) characters\\.","errorType":"validation","errorClass":"HTTPException","httpStatus":422,"severity":"warning","filePath":"src/backend/base/langflow/api/utils/kb_metadata.py","lineNumber":60,"sourceCode":"def _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]:\n    \"\"\"Enforce the user-metadata contract on a decoded dict.\n\n    Returns the same dict (a shallow copy is *not* made — callers may mutate\n    safely once validation passes). Raises :class:`HTTPException` with a 422\n    status on any violation so FastAPI surfaces an inline error.\n    \"\"\"\n    if not isinstance(metadata, dict):\n        msg = \"Metadata must be a JSON object.\"\n        raise HTTPException(status_code=422, detail=msg)\n    if len(metadata) > KB_METADATA_MAX_KEYS:\n        msg = f\"Metadata exceeds the {KB_METADATA_MAX_KEYS} key limit.\"\n        raise HTTPException(status_code=422, detail=msg)","sourceCodeStart":42,"sourceCodeEnd":78,"githubUrl":"https://github.com/langflow-ai/langflow/blob/976ec789d2886a86de109c044d089d68e96c9a35/src/backend/base/langflow/api/utils/kb_metadata.py#L42-L78","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Truncate each array entry to <=256 chars client-side.","Reconsider what belongs in metadata: long excerpts belong in the ingested document text, not metadata arrays.","Add a client-side assertion over all entries: max(map(len, arr)) <= 256.","For long structured values, store an external reference id in the array and keep content elsewhere."],"exampleFix":"# before\nmetadata = {\"quotes\": [paragraph_1, paragraph_2]}  # paragraphs > 256 chars\n\n# after\nMAX = 256\nmetadata = {\"quotes\": [q[:MAX] for q in quotes]}  # or drop quotes from metadata entirely","handlingStrategy":"validation","validationCode":"from langflow.utils.kb_constants import KB_METADATA_MAX_VALUE_LENGTH as MAXV\n\ndef cap_array_entries(meta: dict) -> dict:\n    return {\n        k: ([e[:MAXV] for e in v] if isinstance(v, list) else v)\n        for k, v in meta.items()\n    }","typeGuard":"def array_entries_within_limit(v) -> bool:\n    return not isinstance(v, list) or all(len(e) <= 256 for e in v)","tryCatchPattern":"try:\n    validate_user_metadata(meta)\nexcept HTTPException as e:\n    if e.status_code == 422 and 'array entry' in e.detail and 'exceeds' in e.detail:\n        meta = cap_array_entries(meta); validate_user_metadata(meta)\n    else:\n        raise","preventionTips":["Apply the same 256-char cap to every array entry, not just scalar values.","Keep excerpts/paragraphs out of tag arrays entirely.","Add max(map(len, arr)) <= 256 to your pre-submit assertions."],"tags":["knowledge-base","metadata","validation","http-422","limits"],"backgroundTag":null,"analyzedSha":"976ec789d2886a86de109c044d089d68e96c9a35","analyzedAt":"2026-08-14T18:23:12.227Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}