{"record":{"id":"22a74f3a1821151d","repo":"chroma-core/chroma","slug":"cannot-create-index-on-special-key-key-this","errorCode":null,"errorMessage":"Cannot create index on special key '${key}'. This key is managed automatically by the system. Invoke createIndex(new VectorIndexConfig(...)) without specifying a key to configure the vector index globally.","messagePattern":"Cannot create index on special key '(.+?)'\\. This key is managed automatically by the system\\. Invoke 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":517,"sourceCode":"   */\n  setCmek(cmek: Cmek | null): this {\n    this.cmek = cmek;\n    return this;\n  }\n\n  createIndex(config?: IndexConfig, key?: string): this {\n    const configProvided = config !== undefined && config !== null;\n    const keyProvided = key !== undefined && key !== null;\n\n    if (!configProvided && !keyProvided) {\n      throw new Error(\n        \"Cannot enable all index types globally. Must specify either config or key.\",\n      );\n    }\n\n    // Disallow using special internal key #embedding\n    if (keyProvided && key && key === EMBEDDING_KEY) {\n      throw new Error(\n        `Cannot create index on special key '${key}'. This key is managed automatically by the system. Invoke createIndex(new VectorIndexConfig(...)) without specifying a key to configure the vector index globally.`,\n      );\n    }\n\n    // Only allow #document with FtsIndexConfig\n    if (\n      keyProvided &&\n      key === DOCUMENT_KEY &&\n      !(config instanceof FtsIndexConfig)\n    ) {\n      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(","sourceCodeStart":499,"sourceCodeEnd":535,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/clients/new-js/packages/chromadb/src/schema.ts#L499-L535","documentation":"'#embedding' is the system-managed schema key that stores the collection's vectors; the Schema class seeds and configures it automatically. createIndex therefore refuses any call that explicitly targets '#embedding' — the vector index is configured globally via createIndex(new VectorIndexConfig(...)) without a key, as the error message itself instructs.","triggerScenarios":"schema.createIndex(new VectorIndexConfig(), '#embedding'); createIndex(cfg, '#embedding') with any config; a loop over schema.keys that includes system keys and calls createIndex for each entry.","commonSituations":"Programmatically creating indexes by iterating Schema keys and forgetting to exclude system keys; assuming per-field vector indexes exist (there is one vector index per collection).","solutions":["Configure the vector index globally: call createIndex(new VectorIndexConfig(...)) with NO key argument.","Skip system keys (anything starting with '#') when creating indexes programmatically."],"exampleFix":"// before\nschema.createIndex(new VectorIndexConfig(), '#embedding');\n\n// after\nschema.createIndex(new VectorIndexConfig()); // global, no key","handlingStrategy":"validation","validationCode":"const SYSTEM_KEYS = new Set(['#embedding', '#document']);\nfor (const [key, cfg] of indexPlan) {\n  if (SYSTEM_KEYS.has(key)) continue;\n  schema.createIndex(cfg, key);\n}","typeGuard":"const isSystemKey = (key: string): boolean =>\n  key === '#embedding' || key === '#document';","tryCatchPattern":"try {\n  schema.createIndex(cfg, key);\n} catch (e) {\n  if (e instanceof Error && e.message.includes('#embedding')) {\n    // skip system keys when applying a config catalog\n  } else {\n    throw e;\n  }\n}","preventionTips":["Filter system keys before programmatic index creation.","Remember the layout: vector index is global (no key), FTS belongs to '#document', everything else uses user keys."],"tags":["schema","index-config","reserved-key","chroma"],"backgroundTag":"invalid-index-configuration","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}