colinhacks/zod · error · ZodError

invalid_arguments

invalid_arguments

Error message

Invalid function arguments

What it means

Thrown as a ZodError with code 'invalid_arguments' at packages/zod/src/v3/types.ts:3892 when a function wrapped by z.function() is invoked and its argument tuple fails the args schema validation. The wrapper parses the runtime args array through the configured ZodTuple, and on failure throws a ZodError (not a generic Error) so callers can read the structured issues.

Source

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

        });
        const result = await Reflect.apply(fn, this, parsedArgs as any);
        const parsedReturns = await (me._def.returns as unknown as ZodPromise<ZodTypeAny>)._def.type
          .parseAsync(result, params)
          .catch((e) => {
            error.addIssue(makeReturnsIssue(result, e));
            throw error;
          });
        return parsedReturns;
      });
    } else {
      // Would love a way to avoid disabling this rule, but we need
      // an alias (using an arrow function was what caused 2651).
      // eslint-disable-next-line @typescript-eslint/no-this-alias
      const me = this;
      return OK(function (this: any, ...args: any[]) {
        const parsedArgs = me._def.args.safeParse(args, params);
        if (!parsedArgs.success) {
          throw new ZodError([makeArgsIssue(args, parsedArgs.error)]);
        }
        const result = Reflect.apply(fn, this, parsedArgs.data);
        const parsedReturns = me._def.returns.safeParse(result, params);
        if (!parsedReturns.success) {
          throw new ZodError([makeReturnsIssue(result, parsedReturns.error)]);
        }
        return parsedReturns.data;
      }) as any;
    }
  }

  parameters() {
    return this._def.args;
  }

  returnType() {
    return this._def.returns;
  }

View on GitHub (pinned to 2d90846af9)

Solutions

1. Inspect the thrown ZodError.issues — each issue's path points at the offending argument index.
2. Align the call site with the declared args schema (correct types and order).
3. If the args schema is too strict, relax it (e.g. add .optional(), accept a union) and re-implement.
4. Wrap the invocation in try/catch to translate the ZodError into a domain-specific error for upstream callers.

Example fix

// before
const fn = z
  .function()
  .args(z.string(), z.number())
  .implement((s, n) => `${s}:${n}`);
fn(123, 'x'); // throws invalid_arguments

// after
fn('count', 42);

// Validate arguments before invoking the implemented function.
import { ZodFunction } from 'zod';

function callSafely<Fn extends ZodFunction<any, any>>(fn: Fn, args: unknown[]) {
  const argsSchema = fn.parameters();
  const parsed = argsSchema.safeParse(args);
  if (!parsed.success) {
    return { ok: false as const, error: parsed.error };
  }
  return { ok: true as const, value: fn(...(parsed.data as unknown[])) };
}

null

import { ZodError } from 'zod';

try {
  fn('count', 42);
} catch (e) {
  if (e instanceof ZodError && e.issues.some((i) => i.code === 'invalid_arguments')) {
    // argument contract violation — e.issues[].path points at the bad arg index
    reportArgErrors(e.issues);
  } else {
    throw e;
  }
}

When it happens

Trigger: Defining `const fn = z.function().args(z.string(), z.number()).implement((s, n) => ...)` and then calling `fn(123, 'x')` — the first arg is not a string and the second is not a number, so the args tuple safeParse fails and the wrapper throws invalid_arguments.

Common situations: Calling an implemented ZodFunction from untyped caller code; widening the args schema (e.g. requiring a string) without updating call sites; passing the wrong number of arguments because the tuple/rest shape changed; interop with frameworks that pass extra/positional args.

Related errors

• invalid_return_type
• Not a ZodError: ${value}
• You must pass an array of schemas to z.tuple([ ... ])
• Unrecognized hash format: ${format}
• Invalid UUID version: "${def.version}"

AI-assisted analysis of colinhacks/zod@2d90846af9 (2026-08-11). Data as JSON: /api/errors/f5357cfaf9470bd5. Report an issue: GitHub.