{"record":{"id":"9c1ff390d2d91699","repo":"chroma-core/chroma","slug":"sparse-vector-index-must-be-created-on-a-specific","errorCode":null,"errorMessage":"Sparse vector index must be created on a specific key. Please specify a key using: createIndex(new SparseVectorIndexConfig(...), 'your_key')","messagePattern":"Sparse vector index must be created on a specific key\\. Please specify a key using: createIndex\\(new SparseVectorIndexConfig\\(\\.\\.\\.\\), 'your_key'\\)","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"clients/new-js/packages/chromadb/src/schema.ts","lineNumber":562,"sourceCode":"        return this;\n      }\n      throw new Error(\n        \"Vector index cannot be enabled on specific keys. Use createIndex(new VectorIndexConfig(...)) without specifying a key to configure the vector index globally.\",\n      );\n    }\n\n    // FTS index is only allowed on #document key\n    if (\n      config instanceof FtsIndexConfig &&\n      (!keyProvided || key !== DOCUMENT_KEY)\n    ) {\n      throw new Error(\n        \"FTS index can only be enabled on #document key. Use createIndex(new FtsIndexConfig(), '#document')\",\n      );\n    }\n\n    if (config instanceof SparseVectorIndexConfig && !keyProvided) {\n      throw new Error(\n        \"Sparse vector index must be created on a specific key. Please specify a key using: createIndex(new SparseVectorIndexConfig(...), 'your_key')\",\n      );\n    }\n\n    // TODO: Consider removing this check in the future to allow enabling all indexes for a key\n    // Disallow enabling all index types for a key (config=undefined, key=\"some_key\")\n    if (!configProvided && keyProvided && key) {\n      throw new Error(\n        `Cannot enable all index types for key '${key}'. Please specify a specific index configuration.`,\n      );\n    }\n\n    if (configProvided && !keyProvided) {\n      this.setIndexInDefaults(config as IndexConfig, true);\n    } else if (configProvided && keyProvided && key) {\n      this.setIndexForKey(key, config as IndexConfig, true);\n    }\n","sourceCodeStart":544,"sourceCodeEnd":580,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/clients/new-js/packages/chromadb/src/schema.ts#L544-L580","documentation":"Sparse vector indexes are per-key — each one targets a specific sparse embedding field — so SparseVectorIndexConfig cannot be applied globally. createIndex(new SparseVectorIndexConfig(...)) with no key throws; the message shows the required call shape including the key argument.","triggerScenarios":"schema.createIndex(new SparseVectorIndexConfig()); copying the global VectorIndexConfig pattern for sparse indexes; a config-driven loop where the key variable defaults to undefined for sparse entries.","commonSituations":"Hybrid search (dense + sparse) setups adding sparse indexes; uniformly applying an index catalog where some entries lack target keys.","solutions":["Pass the target field: createIndex(new SparseVectorIndexConfig(...), 'your_sparse_key').","Make the key a required parameter in your own wrapper around sparse index creation."],"exampleFix":"// before\nschema.createIndex(new SparseVectorIndexConfig());\n\n// after\nschema.createIndex(new SparseVectorIndexConfig(), 'sparse_embedding');","handlingStrategy":"validation","validationCode":"function createSparseIndex(schema: Schema, config: SparseVectorIndexConfig, key: string): void {\n  if (!key) throw new Error('Sparse vector index requires an explicit key');\n  schema.createIndex(config, key);\n}","typeGuard":"const isKeyedIndexConfig = (config: IndexConfig): boolean =>\n  config instanceof SparseVectorIndexConfig;","tryCatchPattern":"try {\n  schema.createIndex(config);\n} catch (e) {\n  if (e instanceof Error && e.message.includes('Sparse vector index must be created on a specific key')) {\n    schema.createIndex(config, 'sparse_embedding'); // retry with the target key\n  } else {\n    throw e;\n  }\n}","preventionTips":["Model sparse index creation in your own wrapper with a required key parameter.","Keep per-key vs global requirements in a small config-type table your team references."],"tags":["schema","index-config","sparse-vector","chroma"],"backgroundTag":"invalid-index-configuration","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}