{"record":{"id":"09bcd13be22d3677","repo":"chroma-core/chroma","slug":"schema-is-missing-keys-embedding-key","errorCode":null,"errorMessage":"Schema is missing keys[{embedding_key}]","messagePattern":"Schema is missing keys\\[(.+?)\\]","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"chromadb/api/collection_configuration.py","lineNumber":836,"sourceCode":"\n    Args:\n        schema: The existing Schema object\n        configuration: The configuration updates to apply\n\n    Returns:\n        Updated Schema object\n    \"\"\"\n\n    # Get the vector index from defaults and #embedding key\n    if (\n        schema.defaults.float_list is None\n        or schema.defaults.float_list.vector_index is None\n    ):\n        raise ValueError(\"Schema is missing defaults.float_list.vector_index\")\n\n    embedding_key = \"#embedding\"\n    if embedding_key not in schema.keys:\n        raise ValueError(f\"Schema is missing keys[{embedding_key}]\")\n\n    embedding_value_types = schema.keys[embedding_key]\n    if (\n        embedding_value_types.float_list is None\n        or embedding_value_types.float_list.vector_index is None\n    ):\n        raise ValueError(\n            f\"Schema is missing keys[{embedding_key}].float_list.vector_index\"\n        )\n\n    # Update vector index config in both locations\n    for vector_index in [\n        schema.defaults.float_list.vector_index,\n        embedding_value_types.float_list.vector_index,\n    ]:\n        if \"hnsw\" in configuration and configuration[\"hnsw\"] is not None:\n            # Update HNSW config\n            if vector_index.config.hnsw is None:","sourceCodeStart":818,"sourceCodeEnd":854,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/chromadb/api/collection_configuration.py#L818-L854","documentation":"This ValueError from update_schema_from_collection_configuration is raised when applying a configuration update to a Schema that has no '#embedding' key. The #embedding key is the well-known name for the column holding vector embeddings; without it there is nothing to attach index updates to, so the modify is rejected. It typically signals a schema built without embeddings support or a malformed/custom schema.","triggerScenarios":"Calling client.modify_collection/collection.modify with an hnsw/spann (or embedding-function) update on a collection whose Schema.keys does not contain '#embedding' — for instance a collection created only for metadata/full-text storage, restored from an incompatible older version, or a schema assembled by hand in tests.","commonSituations":"Modifying collections that were created without embedding data or with very old Chroma versions lacking the #embedding convention; custom server builds; data restored from a dump with a lossy schema.","solutions":["Only call modify with index/embedding updates on collections that actually contain embeddings (verify '#embedding' is in the schema keys via collection introspection)","Recreate the collection with a proper embedding configuration and re-ingest if the schema is permanently malformed","Upgrade client and server to matching current versions before modifying legacy collections"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"def collection_likely_has_embeddings(collection) -> bool:\n    try:\n        peek = collection.get(limit=1, include=['embeddings'])\n        return bool(peek['ids'])\n    except Exception:\n        return False\n\nif collection_likely_has_embeddings(collection):\n    collection.modify(configuration=update)","typeGuard":null,"tryCatchPattern":"try:\n    collection.modify(configuration=update)\nexcept ValueError as e:\n    if 'Schema is missing keys[#embedding]' in str(e):\n        # recreate collection with a full configuration and re-ingest\n        migrate_to_new_collection(collection)\n    else:\n        raise","preventionTips":["Only apply embedding/index updates to collections created with embeddings","Keep client/server versions matched so the #embedding convention holds","Recreate-and-reingest rather than repairing malformed schemas in place"],"tags":["chroma","schema","embedding-key","modify-collection","internal-invariant"],"backgroundTag":"schema-validation-failed","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}