{"record":{"id":"9dfbb87616d024ca","repo":"chroma-core/chroma","slug":"cannot-create-index-on-special-key-key-with-t","errorCode":null,"errorMessage":"Cannot create index on special key '${key}' with this config. Only FtsIndexConfig is allowed for #document.","messagePattern":"Cannot create index on special key '(.+?)' with this config\\. Only FtsIndexConfig is allowed for #document\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"clients/new-js/packages/chromadb/src/schema.ts","lineNumber":528,"sourceCode":"      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(\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(","sourceCodeStart":510,"sourceCodeEnd":546,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/clients/new-js/packages/chromadb/src/schema.ts#L510-L546","documentation":"'#document' is the system key holding document text, and the only index that may be created on it is a full-text search index (FtsIndexConfig). Passing any other config — VectorIndexConfig, SparseVectorIndexConfig, or any non-FTS IndexConfig — together with '#document' is rejected.","triggerScenarios":"schema.createIndex(new VectorIndexConfig(), '#document'); schema.createIndex(new SparseVectorIndexConfig(), '#document'); generic loops that pair every config in a catalog with every key including '#document'.","commonSituations":"Trying to index document text with something other than FTS; uniform 'apply this config to all fields' code; misunderstanding that '#document' exists solely for full-text search.","solutions":["Use the exact supported form: createIndex(new FtsIndexConfig(), '#document').","If you wanted a vector or sparse vector index, target the global config or a user key instead — never '#document'."],"exampleFix":"// before\nschema.createIndex(new VectorIndexConfig(), '#document');\n\n// after\nschema.createIndex(new FtsIndexConfig(), '#document');","handlingStrategy":"validation","validationCode":"function createDocumentIndex(schema: Schema, config: IndexConfig): void {\n  if (config instanceof FtsIndexConfig) {\n    schema.createIndex(config, '#document');\n    return;\n  }\n  throw new Error('Only FtsIndexConfig may be created on #document');\n}","typeGuard":"const isFtsForDocument = (config: IndexConfig, key?: string): boolean =>\n  config instanceof FtsIndexConfig && (key === undefined || key === '#document');","tryCatchPattern":"try {\n  schema.createIndex(config, key);\n} catch (e) {\n  if (e instanceof Error && e.message.includes('Only FtsIndexConfig is allowed for #document')) {\n    // switch to createIndex(new FtsIndexConfig(), '#document') or target a user key\n  } else {\n    throw e;\n  }\n}","preventionTips":["Special-case '#document' in index catalogs: FTS is the only legal config there.","Do not apply one config uniformly across all keys including system keys."],"tags":["schema","index-config","full-text-search","chroma"],"backgroundTag":"invalid-index-configuration","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}