{"record":{"id":"0fc0b386b2206430","repo":"chroma-core/chroma","slug":"key-cannot-begin-with-keys-starting-with","errorCode":null,"errorMessage":"key cannot begin with '#'. Keys starting with '#' are reserved for system use.","messagePattern":"key cannot begin with '#'\\. Keys starting with '#' are reserved for system use\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"clients/new-js/packages/chromadb/src/schema.ts","lineNumber":535,"sourceCode":"      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(\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 &&","sourceCodeStart":517,"sourceCodeEnd":553,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/clients/new-js/packages/chromadb/src/schema.ts#L517-L553","documentation":"Keys beginning with '#' are reserved for Chroma system keys ('#document' and '#embedding'). By the time this check runs, the legitimate '#document'+FTS combination has already been handled, so any user-supplied index key starting with '#' is rejected. Rename the key — the namespace cannot be opted into.","triggerScenarios":"schema.createIndex(cfg, '#meta'); a metadata field literally named '#tag' or '#section' used as an index key; templating that prefixes keys with '#' ('#' + fieldName).","commonSituations":"Hashtag-like metadata names coming from social/content pipelines; URL-fragment style ids; accidental string concatenation that prepends '#'.","solutions":["Rename the indexed key so it does not start with '#'.","Strip a leading '#' when mapping external field names to schema keys.","Leave '#document' and '#embedding' to their dedicated FTS/vector index paths."],"exampleFix":"// before\nschema.createIndex(cfg, '#' + fieldName);\n\n// after\nschema.createIndex(cfg, fieldName.replace(/^#/, ''));","handlingStrategy":"type-guard","validationCode":"const safeKey = (key: string) => key.replace(/^#/, '');\nschema.createIndex(cfg, safeKey(externalFieldName));","typeGuard":"const isUserIndexKey = (key: string): boolean =>\n  !key.startsWith('#');","tryCatchPattern":"try {\n  schema.createIndex(cfg, key);\n} catch (e) {\n  if (e instanceof Error && e.message.includes(\"cannot begin with '#'\")) {\n    // strip the leading '#' and retry\n  } else {\n    throw e;\n  }\n}","preventionTips":["Sanitize external field names before using them as index keys.","Treat '#' as a reserved prefix in your metadata naming conventions."],"tags":["schema","index-config","reserved-key","naming","chroma"],"backgroundTag":"invalid-index-configuration","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}