colinhacks/zod · error · Error

You must pass an array of schemas to z.tuple([ ... ])

Error message

You must pass an array of schemas to z.tuple([ ... ])

What it means

Thrown by z.tuple.create when its first argument is not an array. The v3 signature overloads to require an array of schemas, so passing a single schema, a rest spread, or an object fails the runtime Array.isArray guard before construction.

Source

Thrown at packages/zod/src/v3/types.ts:3468

  }

  get items() {
    return this._def.items;
  }

  rest<RestSchema extends ZodTypeAny>(rest: RestSchema): ZodTuple<T, RestSchema> {
    return new ZodTuple({
      ...this._def,
      rest,
    });
  }

  static create = <Items extends [ZodTypeAny, ...ZodTypeAny[]] | []>(
    schemas: Items,
    params?: RawCreateParams
  ): ZodTuple<Items, null> => {
    if (!Array.isArray(schemas)) {
      throw new Error("You must pass an array of schemas to z.tuple([ ... ])");
    }
    return new ZodTuple({
      items: schemas,
      typeName: ZodFirstPartyTypeKind.ZodTuple,
      rest: null,
      ...processCreateParams(params),
    });
  };
}

/////////////////////////////////////////
/////////////////////////////////////////
//////////                     //////////
//////////      ZodRecord      //////////
//////////                     //////////
/////////////////////////////////////////
/////////////////////////////////////////
export interface ZodRecordDef<Key extends KeySchema = ZodString, Value extends ZodTypeAny = ZodTypeAny>

View on GitHub (pinned to 912f0f51b0)

Solutions

1. Wrap schemas in an array literal: `z.tuple([a, b])`.
2. Use z.array for a homogeneous list of one schema type.
3. If spreading, wrap: `z.tuple([...rest])`.

Example fix

// before
z.tuple(z.string(), z.number());

// after
z.tuple([z.string(), z.number()]);

function assertTupleSchemas(schemas: unknown) {
  if (!Array.isArray(schemas)) {
    throw new TypeError("Expected an array of Zod schemas");
  }
}

function isZodSchemaArray(x: unknown): x is z.ZodTypeAny[] {
  return Array.isArray(x) && x.every((s) => s instanceof z.ZodType);
}

When it happens

Trigger: Calling `z.tuple(z.string())`, `z.tuple(...schemas)`, or `z.tuple({0: z.string()})` instead of `z.tuple([z.string()])`. Also triggered by tooling that strips array brackets when generating code.

Common situations: Code-generation bugs; refactoring a single-element tuple and dropping the brackets; confusing z.tuple (positional, array) with z.array (homogeneous) or z.tuple with z.object.

Related errors

• Can't use "invalid_type_error" or "required_error" in conjun
• Synchronous parse encountered promise.
• A discriminator value for key `${discriminator}` could not b
• Discriminator property ${String(discriminator)} has duplicat
• Async refinement encountered during synchronous parse operat

AI-assisted analysis of colinhacks/zod@912f0f51b0 (2026-08-03). Data as JSON: /data/errors/4e6d52932af3ce4b.json. Report an issue: GitHub.