langflow-ai/langflow · error · HTTPException

Error listing metadata keys.

Error message

Error listing metadata keys.

What it means

A 500 from the metadata-keys listing endpoint when iter_documents() raises while scanning the KB to collect distinct metadata keys and values. Mirrors the chunks endpoint: iteration errors over the vector store are logged ('iter_documents failed while listing metadata keys') and converted to this generic detail. Value buckets are capped at KB_METADATA_KEYS_VALUES_CAP with a truncated flag, but that is a normal result, not this error.

Source

Thrown at src/backend/base/langflow/api/v1/knowledge_bases.py:1786

                            continue
                        bucket = distinct.setdefault(key, {})
                        # Array-valued metadata expands into one distinct value
                        # per array entry so the popover dropdown shows every
                        # tag that could be filtered on.
                        candidates = value if isinstance(value, list) else [value]
                        for candidate in candidates:
                            if candidate is None:
                                continue
                            stringified = str(candidate)
                            if stringified in bucket:
                                continue
                            if len(bucket) >= KB_METADATA_KEYS_VALUES_CAP:
                                truncated = True
                                break
                            bucket[stringified] = None
        except Exception as iter_error:
            await logger.aerror("iter_documents failed while listing metadata keys for '%s': %s", kb_name, iter_error)
            raise HTTPException(status_code=500, detail="Error listing metadata keys.") from iter_error

        return KbMetadataKeysResponse(
            keys={key: list(values.keys()) for key, values in sorted(distinct.items())},
            truncated=truncated,
        )

    except HTTPException:
        raise
    except Exception as e:
        await logger.aerror("Error listing metadata keys for '%s': %s", kb_name, e)
        raise HTTPException(status_code=500, detail="Error listing metadata keys.") from e
    finally:
        if backend is not None:
            try:
                await backend.teardown()
            except Exception as teardown_exc:  # noqa: BLE001
                await logger.adebug("Backend teardown failed: %s", teardown_exc)
        if kb_path is not None and backend_type_value == BackendType.CHROMA.value:

View on GitHub (pinned to 976ec789d2)

Solutions

1. Check server logs for the underlying iter_documents exception.
2. Resolve vector-store connectivity or lock contention.
3. Verify the KB's chunks endpoint also works (GET /{kb_name}/chunks) to confirm it is the store, not the metadata path.
4. Recreate/re-ingest the KB if the collection is corrupted.

try:
    keys = await client.get(f"/api/v1/knowledge_bases/{kb}/metadata/keys").json()
except HTTPStatusError as e:
    if e.response.status_code == 500:
        check_server_log(f"iter_documents failed while listing metadata keys for '{kb}'")
        await degrade_gracefully()  # hide metadata filter UI until store recovers

When it happens

Trigger: GET /api/v1/knowledge_bases/{kb_name}/metadata/keys (metadata key listing) while the vector-store backend raises during document iteration — corrupted collection, concurrent lock, or remote store unreachable.

Common situations: Same class of failure as chunk iteration: corrupted Chroma data, concurrent writers, or network/credential issues with remote backends.

Related errors

• Error getting knowledge base.
• Error getting chunks.
• Metadata value for '{key}' exceeds {KB_METADATA_MAX_VALUE_LE
• Metadata array '{key}' exceeds {KB_METADATA_MAX_ARRAY_LENGTH
• Metadata array '{key}' must contain only strings.

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