chroma-core/chroma · error · Error

Invalid SPANN config provided in UpdateCollectionConfigurati

Error message

Invalid SPANN config provided in UpdateCollectionConfiguration

What it means

updateCollectionConfigurationToJson's SPANN shape check: if the spann field of an UpdateCollectionConfiguration is truthy but typeof is not 'object', this plain Error is thrown before the network request. UpdateSpannConfiguration is a partial object deserialized from fields like { search_nprobe, ef_search }; only those keys are copied into the payload (see the sibling updateSpannConfigurationFromJson helper).

Source

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

  }
  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);
  }

  // Construct the result object, only including defined fields
  const result: Record<string, any> = {};
  if (hnswConfig !== undefined) result.hnsw = hnswConfig;
  if (spannConfig !== undefined) result.spann = spannConfig;
  if (efConfig !== undefined) result.embedding_function = efConfig;

  // Check if the result is empty, which means no valid update fields were provided
  if (Object.keys(result).length === 0) {

View on GitHub (pinned to aecdd12c8a)

Solutions

Use the object form: { spann: { search_nprobe: 10, ef_search: 64 } }.
Parse string sources with JSON.parse before assignment.
Add a typeof cfg.spann === 'object' validation step in your update helper.

Example fix

// before
await col.modify({ configuration: { spann: 10 } });

// after
await col.modify({ configuration: { spann: { search_nprobe: 10 } } });

Defensive patterns

Strategy: type-guard

Validate before calling

if (cfg.spann !== undefined && typeof cfg.spann !== 'object') {
  throw new TypeError('update spann must be an object like { search_nprobe: 10 }');
}

Type guard

function isUpdateSpann(v: unknown): v is UpdateSpannConfiguration {
  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 SPANN config provided in UpdateCollectionConfiguration')) {
    // replace the primitive with an options object and retry
  }
  throw e;
}

Prevention

Search nprobe is a field inside the object, not the object itself.
Validate the shape at your config boundary instead of trusting env/queue payloads.
Keep SPANN update snippets in one shared helper so the correct shape is enforced once.

When it happens

Trigger: collection.modify({ configuration: { spann: 10 } }); spann: 'nprobe 10'; spann set from an unparsed string in a dynamically built update payload.

Common situations: Assuming spann is a number of probes rather than an options object; passing serialized JSON from a job queue message; merging loose env-var strings into the update configuration.

Related errors

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