What causes "Unrecognized hash format: ${format}" in colinhacks/zod?

Use one of the supported algorithms: md5, sha1, sha256, sha384, or sha512.

colinhacks/zod · error · Error

Unrecognized hash format: ${format}

Error message

Unrecognized hash format: ${format}

What it means

Thrown by z.hash(alg, { enc }) in the v4 classic API when the assembled format string `${alg}_${enc}` does not map to a known entry in core.regexes. At the type level Alg and Enc are constrained, but the runtime lookup guards against arbitrary string casts or future registry mismatches.

Source

Thrown at packages/zod/src/v4/classic/schemas.ts:1022

export function hostname(_params?: string | core.$ZodStringFormatParams): ZodCustomStringFormat<"hostname"> {
  return core._stringFormat(ZodCustomStringFormat, "hostname", core.regexes.hostname, _params) as any;
}

export function hex(_params?: string | core.$ZodStringFormatParams): ZodCustomStringFormat<"hex"> {
  return core._stringFormat(ZodCustomStringFormat, "hex", core.regexes.hex, _params) as any;
}

export function hash<Alg extends util.HashAlgorithm, Enc extends util.HashEncoding = "hex">(
  alg: Alg,
  params?: {
    enc?: Enc;
  } & core.$ZodStringFormatParams
): ZodCustomStringFormat<`${Alg}_${Enc}`> {
  const enc = params?.enc ?? "hex";
  const format = `${alg}_${enc}` as const;
  const regex = core.regexes[format as keyof typeof core.regexes] as RegExp;
  if (!regex) throw new Error(`Unrecognized hash format: ${format}`);
  return core._stringFormat(ZodCustomStringFormat, format, regex, params) as any;
}

// ZodNumber
export interface _ZodNumber<Internals extends core.$ZodNumberInternals = core.$ZodNumberInternals>
  extends _ZodType<Internals> {
  gt(value: number, params?: string | core.$ZodCheckGreaterThanParams): this;
  /** Identical to .min() */
  gte(value: number, params?: string | core.$ZodCheckGreaterThanParams): this;
  min(value: number, params?: string | core.$ZodCheckGreaterThanParams): this;
  lt(value: number, params?: string | core.$ZodCheckLessThanParams): this;
  /** Identical to .max() */
  lte(value: number, params?: string | core.$ZodCheckLessThanParams): this;
  max(value: number, params?: string | core.$ZodCheckLessThanParams): this;
  /** Consider `z.int()` instead. This API is considered *legacy*; it will never be removed but a better alternative exists. */
  int(params?: string | core.$ZodCheckNumberFormatParams): this;
  /** @deprecated This is now identical to `.int()`. Only numbers in the safe integer range are accepted. */
  safe(params?: string | core.$ZodCheckNumberFormatParams): this;

View on GitHub (pinned to 912f0f51b0)

Solutions

Use one of the supported algorithms: md5, sha1, sha256, sha384, or sha512.
Use a supported encoding: hex (default), base64, or base64url.
For an unsupported format, build a custom string format with z.string().refine() / z4.stringFormat() and your own regex.

Example fix

// before
z.hash('sha3' as any);
z.hash('sha256', { enc: 'ascii' as any });

// after
z.hash('sha256');
z.hash('sha512', { enc: 'base64url' });

Defensive patterns

Strategy: type-guard

Validate before calling

const ALGS = new Set(["md5","sha1","sha256","sha384","sha512"]);
const ENCS = new Set(["hex","base64","base64url"]);
function assertHashParams(alg: string, enc = "hex") {
  if (!ALGS.has(alg)) throw new Error(`Unsupported hash algorithm: ${alg}`);
  if (!ENCS.has(enc)) throw new Error(`Unsupported hash encoding: ${enc}`);
}

Type guard

function isSupportedAlg(a: string): a is "md5"|"sha1"|"sha256"|"sha384"|"sha512" {
  return ["md5","sha1","sha256","sha384","sha512"].includes(a);
}
function isSupportedEnc(e: string): e is "hex"|"base64"|"base64url" {
  return ["hex","base64","base64url"].includes(e);
}

Prevention

Constrain user input for hash algorithm/encoding with an allow-list enum.
Avoid `as any` casts when calling z.hash — let the type system catch mistakes.
For unsupported hashes, register a custom string format with your own regex.

When it happens

Trigger: Calling `z.hash('sha3' as any)` with an algorithm outside the supported set (md5, sha1, sha256, sha384, sha512), or `z.hash('sha256', { enc: 'ascii' as any })` with an encoding other than hex/base64/base64url.

Common situations: Casting string literals with `as any` to bypass the type guard; user-driven algorithm selection feeding an unsupported value; code targeting a hash family zod does not bundle a regex for.

Related errors

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