{"record":{"id":"4e6d52932af3ce4b","repo":"colinhacks/zod","slug":"you-must-pass-an-array-of-schemas-to-z-tuple","errorCode":null,"errorMessage":"You must pass an array of schemas to z.tuple([ ... ])","messagePattern":"You must pass an array of schemas to z\\.tuple\\(\\[ \\.\\.\\. \\]\\)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/zod/src/v3/types.ts","lineNumber":3468,"sourceCode":"  }\n\n  get items() {\n    return this._def.items;\n  }\n\n  rest<RestSchema extends ZodTypeAny>(rest: RestSchema): ZodTuple<T, RestSchema> {\n    return new ZodTuple({\n      ...this._def,\n      rest,\n    });\n  }\n\n  static create = <Items extends [ZodTypeAny, ...ZodTypeAny[]] | []>(\n    schemas: Items,\n    params?: RawCreateParams\n  ): ZodTuple<Items, null> => {\n    if (!Array.isArray(schemas)) {\n      throw new Error(\"You must pass an array of schemas to z.tuple([ ... ])\");\n    }\n    return new ZodTuple({\n      items: schemas,\n      typeName: ZodFirstPartyTypeKind.ZodTuple,\n      rest: null,\n      ...processCreateParams(params),\n    });\n  };\n}\n\n/////////////////////////////////////////\n/////////////////////////////////////////\n//////////                     //////////\n//////////      ZodRecord      //////////\n//////////                     //////////\n/////////////////////////////////////////\n/////////////////////////////////////////\nexport interface ZodRecordDef<Key extends KeySchema = ZodString, Value extends ZodTypeAny = ZodTypeAny>","sourceCodeStart":3450,"sourceCodeEnd":3486,"githubUrl":"https://github.com/colinhacks/zod/blob/2d90846af918af9602e088812d63a035d47cdbe4/packages/zod/src/v3/types.ts#L3450-L3486","documentation":"Thrown by ZodTuple.create (packages/zod/src/v3/types.ts:3468) when the first argument is not an array. The v3 API requires the schemas to be passed as a literal array — z.tuple([z.string(), z.number()]) — both for TypeScript tuple inference and because the runtime builds the items list from array indices. Passing the schemas as spread arguments or a non-array value defeats the build.","triggerScenarios":"Calling `z.tuple(z.string(), z.number())` (missing the array), `z.tuple(someObject)`, or `z.tuple(...someIterable)` where the argument does not satisfy Array.isArray. TypeScript usually catches the shape, but loose any-typed or JS callers hit the runtime guard.","commonSituations":"Migrating from another API that takes variadic args; passing a readonly tuple type without conversion; building the schema list dynamically and forgetting to wrap in an array; calling from plain JavaScript where the type signature is not enforced.","solutions":["Wrap the schemas in an array literal: `z.tuple([z.string(), z.number()])`.","If building dynamically, ensure the variable is a real array before passing it: `z.tuple(items as [ZodType, ...ZodType[]])`.","For spreads, materialize the array first (`const items = [...a, ...b]; z.tuple(items)`).","If calling from JS, run a defensive `Array.isArray(schemas)` check before construction."],"exampleFix":"// before\nconst pair = z.tuple(z.string(), z.number());\n\n// after\nconst pair = z.tuple([z.string(), z.number()]);","handlingStrategy":"validation","validationCode":"import { ZodType } from 'zod';\n\nfunction assertTupleSchemas(schemas: unknown): asserts schemas is ZodType[] {\n  if (!Array.isArray(schemas)) {\n    throw new TypeError(`z.tuple() expects an array, got ${typeof schemas}`);\n  }\n}","typeGuard":"import { ZodTypeAny } from 'zod';\n\nfunction isZodTypeArray(v: unknown): v is ZodTypeAny[] {\n  return Array.isArray(v) && v.every((x) => x instanceof ZodTypeAny || (x && typeof x === 'object' && '_def' in x));\n}","tryCatchPattern":"null","preventionTips":["Always call z.tuple as z.tuple([...]) with an array literal.","When building the items list dynamically, materialise it into a real array variable first.","In TypeScript, enable strict checks so non-array arguments fail at compile time.","For JS callers, run a defensive Array.isArray check before construction."],"tags":["tuple","schema-construction","api-usage","arguments"],"backgroundTag":null,"analyzedSha":"2d90846af918af9602e088812d63a035d47cdbe4","analyzedAt":"2026-08-11T01:21:44.015Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-22T11:17:16.035Z"}