{"record":{"id":"4ec236d2c99f428c","repo":"chroma-core/chroma","slug":"config-validation-failed-for-schema-schemaname","errorCode":null,"errorMessage":"Config validation failed for schema '${schemaName}': ${errorPaths}","messagePattern":"Config validation failed for schema '(.+?)': (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"clients/js/packages/chromadb-core/src/schemas/schemaUtils.ts","lineNumber":112,"sourceCode":" * @param config Configuration to validate\n * @param schemaName Name of the schema file (without .json extension)\n * @throws Error if the configuration does not match the schema\n */\nexport function validateConfigSchema(\n  config: Record<string, any>,\n  schemaName: keyof typeof schemaMap,\n): void {\n  const schema = loadSchema(schemaName);\n\n  const validate = ajv.compile(schema);\n  const valid = validate(config);\n\n  if (!valid) {\n    const errors = validate.errors || [];\n    const errorPaths = errors\n      .map((e) => `${e.instancePath || \"/\"}: ${e.message}`)\n      .join(\", \");\n    throw new Error(\n      `Config validation failed for schema '${schemaName}': ${errorPaths}`,\n    );\n  }\n}\n\n/**\n * Get the version of a schema.\n *\n * @param schemaName Name of the schema file (without .json extension)\n * @returns The schema version as a string\n * @throws Error if the schema file does not exist or is not valid JSON\n */\nexport function getSchemaVersion(schemaName: keyof typeof schemaMap): string {\n  const schema = loadSchema(schemaName);\n  return schema.version || \"1.0.0\";\n}\n\n/**","sourceCodeStart":94,"sourceCodeEnd":130,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/clients/js/packages/chromadb-core/src/schemas/schemaUtils.ts#L94-L130","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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.","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`.","Fix key names to snake_case and types to match the schema, then re-run.","After upgrading chromadb packages, diff the schema files if previously-valid configs start failing."],"exampleFix":"// before\nfn.validateConfigUpdate(old, { modelName: \"BAAI/bge-base-en-v1.5\" });\n// -> Config validation failed for schema 'together_ai': : must have required property 'model_name', ...\n// after\nfn.validateConfigUpdate(old, {\n  model_name: \"BAAI/bge-base-en-v1.5\",\n  api_key_env_var: \"CHROMA_TOGETHER_AI_API_KEY\",\n});","handlingStrategy":"validation","validationCode":"// Validate shape before sending to Chroma (mirrors the JSON schemas)\nfunction assertEmbeddingConfig(cfg: Record<string, unknown>, required: string[]) {\n  const missing = required.filter((k) => cfg[k] === undefined);\n  if (missing.length) {\n    throw new Error(`Embedding config missing required fields: ${missing.join(\", \")}`);\n  }\n}\nassertEmbeddingConfig(cfg, [\"model_name\", \"api_key_env_var\"]); // together_ai schema","typeGuard":null,"tryCatchPattern":"try {\n  fn.validateConfig(cfg);\n} catch (e) {\n  const msg = e instanceof Error ? e.message : String(e);\n  const m = msg.match(/Config validation failed for schema '(\\w+)': (.*)$/);\n  if (m) {\n    // m[1] = schema name, m[2] = '<path>: <message>' pairs naming each bad field\n    throw new Error(`Invalid ${m[1]} embedding config: ${m[2]}`);\n  }\n  throw e;\n}","preventionTips":["Use snake_case keys exactly as the provider schema requires; do not camelCase configs.","After upgrading chromadb, re-run config validation on stored configs before deploying (schemas gain required fields).","Type your configs in code (StoredConfig types) instead of passing untyped JSON around."],"tags":["ajv","json-schema","config-validation","embeddings","schema"],"backgroundTag":"schema-validation-failed","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}