chroma-core/chroma · error · Error

Invalid HNSW config provided in UpdateCollectionConfiguratio

Error message

Invalid HNSW config provided in UpdateCollectionConfiguration

What it means

updateCollectionConfigurationToJson validates the hnsw field of an UpdateCollectionConfiguration: present-but-not-an-object throws this plain Error. UpdateHNSWConfiguration is a partial object of tunables such as { space, num_neighbors, search_ef, ef_search }; null/undefined are allowed (they mean 'leave unchanged'), but strings/numbers/booleans are not.

Source

Thrown at clients/js/packages/chromadb-core/src/CollectionConfiguration.ts:319

}

export function updateCollectionConfigurationToJson(
  config: UpdateCollectionConfiguration,
): Record<string, any> {
  if (config.hnsw && config.spann) {
    throw new InvalidConfigurationError(
      "Cannot specify both 'hnsw' and 'spann' configurations during update.",
    );
  }
  let hnswConfig = config.hnsw;
  let spannConfig = config.spann;
  let ef = config.embedding_function;
  let efConfig: Record<string, any> | null | undefined = undefined; // Initialize as undefined

  // Validate HNSW config if present
  if (hnswConfig) {
    if (typeof hnswConfig !== "object") {
      throw new Error(
        "Invalid HNSW config provided in UpdateCollectionConfiguration",
      );
    }
  }

  // Validate SPANN config if present
  if (spannConfig) {
    if (typeof spannConfig !== "object") {
      throw new Error(
        "Invalid SPANN config provided in UpdateCollectionConfiguration",
      );
    }
  }

  // Handle embedding function serialization only if explicitly provided (ef !== undefined)
  if (ef !== undefined) {
    efConfig = serializeEmbeddingFunction(ef);
  }

View on GitHub (pinned to aecdd12c8a)

Solutions

Pass hnsw as an object with only the fields you want to change: { hnsw: { search_ef: 200 } }.
JSON.parse any stringified source before embedding it in the update payload.
Type the payload as UpdateCollectionConfiguration so the compiler catches primitive mistakes.

Example fix

// before
await col.modify({ configuration: { hnsw: process.env.HNSW_UPDATE! } });

// after
await col.modify({ configuration: { hnsw: { search_ef: 200 } } });

Defensive patterns

Strategy: type-guard

Validate before calling

if (cfg.hnsw !== undefined && typeof cfg.hnsw !== 'object') {
  throw new TypeError('update hnsw must be an object of HNSW tunables');
}

Type guard

function isUpdateHnsw(v: unknown): v is UpdateHNSWConfiguration {
  return typeof v === 'object' && v !== null && !Array.isArray(v);
}

Try / catch

try {
  await col.modify({ configuration });
} catch (e) {
  if (e instanceof Error && e.message.includes('Invalid HNSW config provided in UpdateCollectionConfiguration')) {
    // coerce to an object: typeof x === 'string' ? JSON.parse(x) : x
  }
  throw e;
}

Prevention

Type update payloads as UpdateCollectionConfiguration (partial fields) rather than Record<string, any>.
Parse string-sourced tunables with JSON.parse at the config boundary, once.
Unit-test your update builder with undefined/absent fields to catch accidental primitives.

When it happens

Trigger: collection.modify({ configuration: { hnsw: 'search_ef=200' } }); hnsw: process.env.HNSW_UPDATE (unparsed string); hnsw: 10.

Common situations: Reading tuning parameters from env vars or feature-flag services as strings; building the update payload via template literals; misunderstanding the partial-update shape ({ hnsw: { search_ef } } rather than a query-string).

Related errors

AI-assisted analysis of chroma-core/chroma@aecdd12c8a (2026-08-16). Data as JSON: /api/errors/f363e64411c8425d. Report an issue: GitHub.