{"record":{"id":"41ee3e4c90f555e7","repo":"chroma-core/chroma","slug":"invalid-spann-config-provided-in-createcollectionc","errorCode":null,"errorMessage":"Invalid SPANN config provided in CreateCollectionConfiguration","messagePattern":"Invalid SPANN config provided in CreateCollectionConfiguration","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"clients/js/packages/chromadb-core/src/CollectionConfiguration.ts","lineNumber":267,"sourceCode":"): Record<string, any> {\n  if (config.hnsw && config.spann) {\n    throw new InvalidConfigurationError(\n      \"Cannot specify both 'hnsw' and 'spann' configurations during creation.\",\n    );\n  }\n  let hnswConfig = config.hnsw;\n  let spannConfig = config.spann;\n  let ef = config.embedding_function;\n  let efConfig = serializeEmbeddingFunction(ef);\n\n  // Basic validation/casting attempt\n  if (hnswConfig && typeof hnswConfig !== \"object\") {\n    throw new Error(\n      \"Invalid HNSW config provided in CreateCollectionConfiguration\",\n    );\n  }\n  if (spannConfig && typeof spannConfig !== \"object\") {\n    throw new Error(\n      \"Invalid SPANN config provided in CreateCollectionConfiguration\",\n    );\n  }\n\n  return {\n    hnsw: hnswConfig,\n    spann: spannConfig,\n    embedding_function: efConfig,\n  };\n}\n\n// --- Update Configuration Helpers ---\n\nexport function jsonToUpdateHnswConfiguration(\n  jsonMap: Record<string, any>,\n): UpdateHNSWConfiguration {\n  const config: UpdateHNSWConfiguration = {};\n  if (\"ef_search\" in jsonMap) config.ef_search = jsonMap.ef_search;","sourceCodeStart":249,"sourceCodeEnd":285,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/clients/js/packages/chromadb-core/src/CollectionConfiguration.ts#L249-L285","documentation":"The SPANN counterpart of the HNSW shape check in createCollectionConfigurationToJson: if the spann field of a CreateCollectionConfiguration is truthy but not an object, this plain Error is thrown before any network call. spann must be a CreateSpannConfiguration object such as { search_nprobe, ef_search } (creation may also carry build params depending on the client version).","triggerScenarios":"configuration: { spann: 'nprobe:10' }; configuration: { spann: JSON.parse-less string from config file }; configuration: { spann: true } used as an 'enable SPANN' flag.","commonSituations":"Treating spann as a boolean feature flag instead of an options object; feeding stringified config from env vars or secret stores; porting Python dict syntax through string interpolation.","solutions":["Pass a spann options object: configuration: { spann: { search_nprobe: 10, ef_search: 64 } }.","Parse string sources with JSON.parse before assigning them to configuration.spann.","Guard with typeof configuration.spann === 'object' prior to createCollection."],"exampleFix":"// before\nawait client.createCollection({ name: 'x', configuration: { spann: true } });\n\n// after\nawait client.createCollection({ name: 'x', configuration: { spann: { search_nprobe: 10 } } });","handlingStrategy":"type-guard","validationCode":"if (cfg.spann !== undefined && typeof cfg.spann !== 'object') {\n  throw new TypeError('spann config must be an object, e.g. { search_nprobe: 10 }');\n}","typeGuard":"function isSpannConfig(v: unknown): v is CreateSpannConfiguration {\n  return (\n    typeof v === 'object' &&\n    v !== null &&\n    !Array.isArray(v) &&\n    Object.keys(v).every((k) => ['search_nprobe', 'ef_search'].includes(k))\n  );\n}","tryCatchPattern":"try {\n  await client.createCollection({ name, configuration });\n} catch (e) {\n  if (e instanceof Error && e.message.includes('Invalid SPANN config')) {\n    // replace primitive with { search_nprobe, ef_search } object\n  }\n  throw e;\n}","preventionTips":["Treat spann as an options object, not a boolean or a count.","Validate externally sourced configuration with a small schema check before handing it to the client.","Keep one typed config module for collection creation and reuse it everywhere."],"tags":["configuration","validation","spann","type-mismatch","collection-creation"],"backgroundTag":"config-type-mismatch","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}