How validate e164 phone number with custom message in case field is empty?

[evgeniyworkbel]

I want to validate string with custom message in case field is empty. Checks must be in the following order:

1. if string is empty, so schema fails with error "Field is required";
2. if string do not match e164 format, so schema fails with error "Field must be e164 format"

[dosubot[bot]]

Hi @evgeniyworkbel! I'm Dosu and I'm helping the Zod team.

You can achieve this by chaining validators — they execute in the order they're defined, so the first failing check produces the error message the user sees.

Zod 4 (recommended) has a built-in .e164() method [1]:

const phoneSchema = z
  .string({ error: "Field is required" })
  .min(1, "Field is required")
  .e164("Field must be e164 format");

The z.string({ error: "Field is required" }) catches non-string inputs (e.g. undefined), .min(1, ...) catches empty strings, and .e164(...) validates the E.164 format [2].

Zod 3 doesn't have .e164(), so use .regex() instead:

const E164_REGEX = /^\+[1-9]\d{1,14}$/;

const phoneSchema = z
  .string({ required_error: "Field is required" })
  .min(1, "Field is required")
  .regex(E164_REGEX, { message: "Field must be e164 format" });

In both cases:

• "" → fails at .min(1) → "Field is required"
• "555-123" → fails at .e164() / .regex() → "Field must be e164 format"
• "+15555555555" → passes ✅

Note that Zod 3 uses required_error in the constructor options, while Zod 4 uses error [2].

Feel free to close this discussion if that answers your question!

To reply, just mention @dosu.

---

Share context across your team and agents. Try Dosu.

[evgeniyworkbel]

IDE shows typescript warning

(params?: string | { abort?: boolean | undefined; pattern?: RegExp | undefined; error?: string | $ZodErrorMap<$ZodIssueInvalidStringFormat> | undefined; message?: string | undefined; } | undefined): ZodString' is deprecated.ts(6385)
schemas.d.cts(158, 9): The declaration was marked as deprecated here.
deprecated — Use z.e164() instead.

[MentalOfCrow]

Use a pipeline so the E.164 validator is only evaluated after the non-empty check succeeds:

import { z } from "zod";

const phone = z
  .string({
    error: (issue) =>
      issue.input === undefined || issue.input === null
        ? "Field is required"
        : "Field must be a string",
  })
  .trim()
  .min(1, { error: "Field is required" })
  .pipe(z.e164({ error: "Field must be E.164 format" }));

This gives the requested precedence:

phone.safeParse("").error?.issues[0].message;
// "Field is required"

phone.safeParse("   ").error?.issues[0].message;
// "Field is required"

phone.safeParse("555-555-5555").error?.issues[0].message;
// "Field must be E.164 format"

phone.parse("+15555555555");
// "+15555555555"

.pipe(...) matters here: if .min(1) fails, Zod does not run the E.164 schema on that failed value. The error function on z.string() separately handles a missing key/undefined, because that is an invalid_type issue rather than a too_small issue.

The .trim() is optional; keep it if whitespace-only input should count as empty. Zod's built-in z.e164() accepts a leading +, a non-zero country code, and 7–15 digits in total.

If this solves the validation order, please mark it as the accepted answer so future readers can find it easily.