chroma-core/chroma · error

Config validation failed for schema '${schemaName}': ${error

Error message

Config validation failed for schema '${schemaName}': ${errorPaths}

What it means

validateConfigSchema() compiles the per-provider JSON Schema from clients/js/packages/chromadb-core/src/schemas/json/ with Ajv and runs it against the embedding function's config. On failure it concatenates every violation as '<instancePath>: <ajv message>' — instancePath is the JSON pointer to the offending field (e.g. '' for a missing required property, '/model_name' for a bad value). Called from each embedding function's validateConfig/validateConfigUpdate when the config is set on or updated for a collection.

Source

Thrown at clients/js/packages/chromadb-core/src/schemas/schemaUtils.ts:112

 * @param config Configuration to validate
 * @param schemaName Name of the schema file (without .json extension)
 * @throws Error if the configuration does not match the schema
 */
export function validateConfigSchema(
  config: Record<string, any>,
  schemaName: keyof typeof schemaMap,
): void {
  const schema = loadSchema(schemaName);

  const validate = ajv.compile(schema);
  const valid = validate(config);

  if (!valid) {
    const errors = validate.errors || [];
    const errorPaths = errors
      .map((e) => `${e.instancePath || "/"}: ${e.message}`)
      .join(", ");
    throw new Error(
      `Config validation failed for schema '${schemaName}': ${errorPaths}`,
    );
  }
}

/**
 * Get the version of a schema.
 *
 * @param schemaName Name of the schema file (without .json extension)
 * @returns The schema version as a string
 * @throws Error if the schema file does not exist or is not valid JSON
 */
export function getSchemaVersion(schemaName: keyof typeof schemaMap): string {
  const schema = loadSchema(schemaName);
  return schema.version || "1.0.0";
}

/**

View on GitHub (pinned to aecdd12c8a)

Solutions

1. Read each '<path>: <message>' pair in the message — it names exactly which field is missing/invalid; an empty path with 'must have required property' means a top-level key is missing.
2. Open the matching schema, e.g. clients/js/packages/chromadb-core/src/schemas/json/together_ai.json (or voyageai.json, transformers.json, ...), and check `required`, `properties`, and `additionalProperties`.
3. Fix key names to snake_case and types to match the schema, then re-run.
4. After upgrading chromadb packages, diff the schema files if previously-valid configs start failing.

Example fix

// before
fn.validateConfigUpdate(old, { modelName: "BAAI/bge-base-en-v1.5" });
// -> Config validation failed for schema 'together_ai': : must have required property 'model_name', ...
// after
fn.validateConfigUpdate(old, {
  model_name: "BAAI/bge-base-en-v1.5",
  api_key_env_var: "CHROMA_TOGETHER_AI_API_KEY",
});

// Validate shape before sending to Chroma (mirrors the JSON schemas)
function assertEmbeddingConfig(cfg: Record<string, unknown>, required: string[]) {
  const missing = required.filter((k) => cfg[k] === undefined);
  if (missing.length) {
    throw new Error(`Embedding config missing required fields: ${missing.join(", ")}`);
  }
}
assertEmbeddingConfig(cfg, ["model_name", "api_key_env_var"]); // together_ai schema

try {
  fn.validateConfig(cfg);
} catch (e) {
  const msg = e instanceof Error ? e.message : String(e);
  const m = msg.match(/Config validation failed for schema '(\w+)': (.*)$/);
  if (m) {
    // m[1] = schema name, m[2] = '<path>: <message>' pairs naming each bad field
    throw new Error(`Invalid ${m[1]} embedding config: ${m[2]}`);
  }
  throw e;
}

When it happens

Trigger: TogetherAI config missing required model_name or api_key_env_var; passing camelCase keys (apiKeyEnvVar) where the schema wants snake_case; VoyageAI config with model_name of the wrong type (number instead of string); Transformers config missing required model/revision/quantized; extra unknown properties when the schema disallows them.

Common situations: Hand-writing a config for buildFromConfig(); version skew after upgrading the JS client (schema gained required fields); persisting configs in your own DB and restoring them with a stale shape; copying config examples from a different provider's docs.

Related errors

• Bad request to ${input} with status: ${resp.statusText}
• You must provide either queryEmbeddings or queryTexts
• Cloudflare API key is required. Please provide it in the con
• resp.detail || "Unknown error"
• Error calling Cloudflare Workers AI API: ${error.message}

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