{"record":{"id":"41bcaff9cea5e836","repo":"chroma-core/chroma","slug":"vector-index-cannot-be-enabled-on-specific-keys-u","errorCode":null,"errorMessage":"Vector index cannot be enabled on specific keys. Use createIndex(new VectorIndexConfig(...)) without specifying a key to configure the vector index globally.","messagePattern":"Vector index cannot be enabled on specific keys\\. Use createIndex\\(new VectorIndexConfig\\(\\.\\.\\.\\)\\) without specifying a key to configure the vector index globally\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"clients/new-js/packages/chromadb/src/schema.ts","lineNumber":546,"sourceCode":"      throw new Error(\n        `Cannot create index on special key '${key}' with this config. Only FtsIndexConfig is allowed for #document.`,\n      );\n    }\n\n    // Disallow any key starting with # (except #document which allows FTS)\n    if (keyProvided && key && key.startsWith(\"#\") && key !== DOCUMENT_KEY) {\n      throw new Error(\n        \"key cannot begin with '#'. Keys starting with '#' are reserved for system use.\",\n      );\n    }\n\n    // Special handling for vector index\n    if (config instanceof VectorIndexConfig) {\n      if (!keyProvided) {\n        this.setVectorIndexConfig(config);\n        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      );","sourceCodeStart":528,"sourceCodeEnd":564,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/clients/new-js/packages/chromadb/src/schema.ts#L528-L564","documentation":"A collection has exactly one vector index, stored under the system '#embedding' key, so VectorIndexConfig can only be applied collection-wide. Passing any key together with a VectorIndexConfig throws this error; the global form is createIndex(new VectorIndexConfig(...)) with no key argument.","triggerScenarios":"schema.createIndex(new VectorIndexConfig(...), 'embeddings'); loops applying one config to many keys; porting a multi-embedding-field design from a database that supports per-column vector indexes.","commonSituations":"Migrating from pgvector-style schemas with several indexed vector columns; uniformly applying a catalog of configs to all keys; assuming per-field HNSW indexes exist.","solutions":["Call createIndex(new VectorIndexConfig(...)) WITHOUT the key argument.","For multiple embedding fields, use separate collections (or per-key sparse vector indexes where appropriate)."],"exampleFix":"// before\nschema.createIndex(new VectorIndexConfig(), 'my_vector');\n\n// after\nschema.createIndex(new VectorIndexConfig()); // applies globally","handlingStrategy":"validation","validationCode":"function applyIndex(schema: Schema, config: IndexConfig, key?: string): void {\n  if (config instanceof VectorIndexConfig) {\n    schema.createIndex(config); // global only, ignore any key\n    return;\n  }\n  schema.createIndex(config, key);\n}","typeGuard":"const isGlobalOnlyConfig = (config: IndexConfig): boolean =>\n  config instanceof VectorIndexConfig;","tryCatchPattern":"try {\n  schema.createIndex(config, key);\n} catch (e) {\n  if (e instanceof Error && e.message.startsWith('Vector index cannot be enabled on specific keys')) {\n    schema.createIndex(config); // retry globally\n  } else {\n    throw e;\n  }\n}","preventionTips":["Branch on config type before calling createIndex: VectorIndexConfig goes global, always.","For multiple embedding fields, plan separate collections up front."],"tags":["schema","index-config","vector-index","chroma"],"backgroundTag":"invalid-index-configuration","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}