chroma-core/chroma · error · Error

If sourceKey is provided then embeddingFunction must also be

Error message

If sourceKey is provided then embeddingFunction must also be provided since there is no default embedding function. Config: ${JSON.stringify(config)}

What it means

Thrown when enabling a SparseVectorIndexConfig (via Schema.createIndex(config, key), which routes through setIndexForKey → validateSparseVectorConfig) whose sourceKey is set but whose embeddingFunction is not. Sparse vector indexes are produced by an embedding model; there is no default sparse embedding function, so a source key without a function to embed it is meaningless and is rejected before any server call.

Source

Thrown at clients/new-js/packages/chromadb/src/schema.ts:887

      new IntInvertedIndexType(false, new IntInvertedIndexConfig()),
    );
    current.floatValue = new FloatValueType(
      new FloatInvertedIndexType(false, new FloatInvertedIndexConfig()),
    );
    current.boolean = new BoolValueType(
      new BoolInvertedIndexType(false, new BoolInvertedIndexConfig()),
    );
  }

  private validateSparseVectorConfig(config: SparseVectorIndexConfig): void {
    // Validate that if source_key is provided then embedding_function is also provided
    // since there is no default embedding function
    if (
      config.sourceKey !== null &&
      config.sourceKey !== undefined &&
      !config.embeddingFunction
    ) {
      throw new Error(
        `If sourceKey is provided then embeddingFunction must also be provided since there is no default embedding function. Config: ${JSON.stringify(
          config,
        )}`,
      );
    }
  }

  private initializeDefaults(): void {
    this.defaults.string = new StringValueType(
      new FtsIndexType(false, new FtsIndexConfig()),
      new StringInvertedIndexType(true, new StringInvertedIndexConfig()),
    );

    this.defaults.floatList = new FloatListValueType(
      new VectorIndexType(false, new VectorIndexConfig()),
    );

    this.defaults.sparseVector = new SparseVectorValueType(

View on GitHub (pinned to aecdd12c8a)

Solutions

Pass an embedding function together with sourceKey: new SparseVectorIndexConfig({ sourceKey: 'body', embeddingFunction: mySparseEF })
If you already have precomputed sparse vectors, omit sourceKey — you will supply the vectors yourself in metadatas
Re-attach the function after deserializing a schema, since JSON.stringify strips it

Example fix

// before
schema.createIndex(
  new SparseVectorIndexConfig({ sourceKey: "body" }),
  "body_sparse",
);
// after
import { DefaultSparseEmbeddingFunction } from "chromadb";
schema.createIndex(
  new SparseVectorIndexConfig({
    sourceKey: "body",
    embeddingFunction: new DefaultSparseEmbeddingFunction(),
  }),
  "body_sparse",
);

Defensive patterns

Strategy: validation

Validate before calling

function assertSparseConfigReady(cfg) {
  if ((cfg.sourceKey ?? null) !== null && !cfg.embeddingFunction) {
    throw new Error('SparseVectorIndexConfig needs embeddingFunction when sourceKey is set');
  }
}

Type guard

function isSparseConfigComplete(c): c is SparseVectorIndexConfig { return c instanceof SparseVectorIndexConfig && (c.sourceKey == null || !!c.embeddingFunction); }

Try / catch

try { schema.createIndex(cfg, key); } catch (e) { if (e instanceof Error && /embeddingFunction must also be provided/.test(e.message)) throw new Error('Attach a sparse embedding function before enabling this index'); else throw e; }

Prevention

Always construct SparseVectorIndexConfig with sourceKey and embeddingFunction together
Re-hydrate embedding functions after schema deserialization (JSON drops them)
Centralize sparse index setup in one factory function so the pairing cannot be forgotten

When it happens

Trigger: schema.createIndex(new SparseVectorIndexConfig({ sourceKey: 'body' }), 'body_sparse') with no embeddingFunction in the config object. Fires whenever config.sourceKey != null/undefined && !config.embeddingFunction (schema.ts:882-886).

Common situations: Copying a SparseVectorIndexConfig from serialization/JSON where the function was dropped (functions do not survive JSON round-trips); upgrading from an API where the sparse function was inferred; forgetting that sourceKey and embeddingFunction are a paired requirement.

Related errors

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