{"record":{"id":"71ef02a11f039a3e","repo":"colinhacks/zod","slug":"this-schema-contains-multiple-valid-literal-values","errorCode":null,"errorMessage":"This schema contains multiple valid literal values. Use `.values` instead.","messagePattern":"This schema contains multiple valid literal values\\. Use `\\.values` instead\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/zod/src/v4/classic/schemas.ts","lineNumber":2020,"sourceCode":"\n// ZodLiteral\nexport interface ZodLiteral<T extends util.Literal = util.Literal>\n  extends _ZodType<core.$ZodLiteralInternals<T>>,\n    core.$ZodLiteral<T> {\n  \"~standard\": ZodStandardSchemaWithJSON<this>;\n  values: Set<T>;\n  /** @legacy Use `.values` instead. Accessing this property will throw an error if the literal accepts multiple values. */\n  value: T;\n}\nexport const ZodLiteral: core.$constructor<ZodLiteral> = /*@__PURE__*/ core.$constructor(\"ZodLiteral\", (inst, def) => {\n  core.$ZodLiteral.init(inst, def);\n  ZodType.init(inst, def);\n  inst._zod.processJSONSchema = (ctx, json, params) => processors.literalProcessor(inst, ctx, json, params);\n  inst.values = new Set(def.values);\n  Object.defineProperty(inst, \"value\", {\n    get() {\n      if (def.values.length > 1) {\n        throw new Error(\"This schema contains multiple valid literal values. Use `.values` instead.\");\n      }\n      return def.values[0];\n    },\n  });\n});\n\nexport function literal<const T extends ReadonlyArray<util.Literal>>(\n  value: T,\n  params?: string | core.$ZodLiteralParams\n): ZodLiteral<T[number]>;\nexport function literal<const T extends util.Literal>(\n  value: T,\n  params?: string | core.$ZodLiteralParams\n): ZodLiteral<T>;\nexport function literal(value: any, params: any) {\n  return new ZodLiteral({\n    type: \"literal\",\n    values: Array.isArray(value) ? value : [value],","sourceCodeStart":2002,"sourceCodeEnd":2038,"githubUrl":"https://github.com/colinhacks/zod/blob/2d90846af918af9602e088812d63a035d47cdbe4/packages/zod/src/v4/classic/schemas.ts#L2002-L2038","documentation":"Thrown by the legacy `.value` getter on ZodLiteral when the literal schema was built from more than one value (z.literal([a, b, ...])). In Zod v4 a literal can accept an array of values and exposes them via `.values` (a Set); the single-value `.value` getter is kept only for backward compatibility and refuses to pick among multiple values.","triggerScenarios":"Calling `.value` on a schema created with z.literal(['foo','bar']) or z.literal([1,2,3]). Migrating code from a single literal to a multi-value literal without switching property access.","commonSituations":"Upgrading from Zod v3 patterns where `.value` was the only accessor. Generalising a once-single literal into a union of literals and forgetting the read site.","solutions":["Read from `.values` (a Set<T>) instead of `.value` for multi-value literals.","If a single value is genuinely required, construct the literal with a scalar: z.literal('foo') rather than z.literal(['foo']).","When you need the lone value but are unsure, guard with `schema.values.size === 1 ? [...schema.values][0] : undefined`."],"exampleFix":"// before (throws — multiple values)\nconst lit = z.literal(['foo', 'bar']);\nconst v = lit.value;\n\n// after\nconst lit = z.literal(['foo', 'bar']);\nconst vs = lit.values; // Set { 'foo', 'bar' }","handlingStrategy":"type-guard","validationCode":null,"typeGuard":"function isSingleValueLiteral(schema) {\n  // ZodLiteral exposes .values as a Set in v4\n  return schema.values.size === 1;\n}\n\n// usage\nconst v = isSingleValueLiteral(lit) ? lit.value : lit.values;","tryCatchPattern":"try {\n  const v = lit.value;\n} catch (e) {\n  if (e.message.includes('multiple valid literal values')) {\n    const values = lit.values; // Set<T>\n    // handle multi-value case\n  } else {\n    throw e;\n  }\n}","preventionTips":["Prefer `.values` (Set) when reading from literals that may have been built from arrays.","Construct single-value literals with a scalar argument (z.literal(x)) when you intend to use `.value`.","During Zod v3 -> v4 migration, audit every `.value` access on literal schemas."],"tags":["literal","api-misuse","migration","schema-construction"],"backgroundTag":null,"analyzedSha":"2d90846af918af9602e088812d63a035d47cdbe4","analyzedAt":"2026-08-11T01:21:44.015Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-22T11:17:16.035Z"}