{"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/912f0f51b0ced654d0069741e7160834dca742ee/packages/zod/src/v4/classic/schemas.ts#L2002-L2038","documentation":"In Zod v4 `z.literal()` accepts an array of values, producing a multi-value literal schema whose `.values` is a Set (schemas.ts:2016). The legacy single-value `.value` getter (schemas.ts:2017) throws when `def.values.length > 1` because a single value is ambiguous. The getter exists for backwards compatibility and explicitly redirects users to `.values`.","triggerScenarios":"Constructing `z.literal([\"a\", \"b\"])` (or any array with 2+ entries) then reading `.value` on the resulting schema. Also reachable by merging/concatenating literals into a multi-value one.","commonSituations":"Migrating Zod v3 code that read `.value` on literals; building a literal from a dynamically-sized array that happens to contain more than one element; refactoring a single-value literal into a union/multi form without updating `.value` accesses.","solutions":["Switch the read from `.value` to `.values` (a Set); use `[...schema.values][0]` if you specifically need one.","If a single value is semantically required, construct with a scalar: `z.literal(\"a\")` so `.value` stays valid.","Guard the access: `if (schema.values.size === 1) { schema.value } else { ... }`."],"exampleFix":"// before\nconst s = z.literal([\"a\", \"b\"]);\nconst v = s.value; // throws\n// after\nconst s = z.literal([\"a\", \"b\"]);\nconst v = s.values; // Set { \"a\", \"b\" }","handlingStrategy":"type-guard","validationCode":null,"typeGuard":"import { z } from \"zod\";\n\nfunction isSingleValueLiteral(s: z.ZodLiteral<any>): boolean {\n  return s.values.size === 1;\n}\n\nconst v = isSingleValueLiteral(schema) ? schema.value : schema.values;","tryCatchPattern":null,"preventionTips":["Prefer `.values` (Set) for any literal that could be multi-value.","When migrating from v3, audit every `.value` read on literals.","Construct with a scalar `z.literal(x)` when a single value is guaranteed."],"tags":["literal","v4-migration","multi-value","api-change"],"analyzedSha":"912f0f51b0ced654d0069741e7160834dca742ee","analyzedAt":"2026-08-03T17:41:55.908Z","schemaVersion":2}