{"record":{"id":"ef1d9f424fd9a2dc","repo":"chroma-core/chroma","slug":"invalid-hnsw-config-provided-in-createcollectionco","errorCode":null,"errorMessage":"Invalid HNSW config provided in CreateCollectionConfiguration","messagePattern":"Invalid HNSW config provided in CreateCollectionConfiguration","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"clients/js/packages/chromadb-core/src/CollectionConfiguration.ts","lineNumber":262,"sourceCode":"}\n\n// TODO: make warnings prettier and add link to migration docs\nexport function createCollectionConfigurationToJson(\n  config: CreateCollectionConfiguration,\n): 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","sourceCodeStart":244,"sourceCodeEnd":280,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/clients/js/packages/chromadb-core/src/CollectionConfiguration.ts#L244-L280","documentation":"createCollectionConfigurationToJson does a basic shape check on the hnsw field: if it is truthy but typeof is not 'object', it throws this plain Error. The client expects hnsw to be a CreateHNSWConfiguration object ({ space, num_neighbors, search_ef, ... }); note that because of the truthy guard, null/undefined pass, and arrays technically pass the typeof check, so in practice this fires when a primitive (string, number, boolean) is supplied.","triggerScenarios":"configuration: { hnsw: 'cosine' } (string instead of { space: 'cosine' }); configuration: { hnsw: JSON.stringify(hnswCfg) } when the config was read from a file/env var and never parsed; configuration: { hnsw: 42 }.","commonSituations":"Loading collection configuration from environment variables, YAML, or JSON strings and forgetting JSON.parse; passing a serialized config between services; shorthand mistakes where only the space string is given instead of the options object.","solutions":["Pass an object literal: configuration: { hnsw: { space: 'cosine', num_neighbors: 16 } }.","If the config comes from env/file as text, wrap it with JSON.parse before passing: { hnsw: JSON.parse(raw) }.","Add a typeof config.hnsw === 'object' guard before calling createCollection to surface your own error earlier."],"exampleFix":"// before\nconst cfg = process.env.COLLECTION_HNSW; // '{\"space\":\"cosine\"}'\nawait client.createCollection({ name: 'x', configuration: { hnsw: cfg } });\n\n// after\nconst cfg = JSON.parse(process.env.COLLECTION_HNSW!);\nawait client.createCollection({ name: 'x', configuration: { hnsw: cfg } });","handlingStrategy":"type-guard","validationCode":"if (cfg.hnsw !== undefined && typeof cfg.hnsw !== 'object') {\n  throw new TypeError('hnsw config must be an object, e.g. { space: \"cosine\" }');\n}","typeGuard":"function isHnswConfig(v: unknown): v is CreateHNSWConfiguration {\n  return (\n    typeof v === 'object' &&\n    v !== null &&\n    !Array.isArray(v) &&\n    Object.keys(v).every((k) => ['space', 'num_neighbors', 'search_ef', 'ef_search', 'max_neighbors', 'resize_factor', 'batch_size', 'sync_threshold', 'data_normalization'].includes(k))\n  );\n}","tryCatchPattern":"try {\n  await client.createCollection({ name, configuration });\n} catch (e) {\n  if (e instanceof Error && e.message.includes('Invalid HNSW config')) {\n    // hnsw was a primitive: stringify + JSON.parse it, or replace with an object literal\n  }\n  throw e;\n}","preventionTips":["Never JSON.stringify index configs in transit; pass structured objects end to end.","If config comes from env/YAML, parse and validate it once at startup with a schema check.","Let TypeScript do the work: declare the payload as CreateCollectionConfiguration so strings fail to compile."],"tags":["configuration","validation","hnsw","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"}