Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Next.js and React

Yup string().matches() rejects values that should pass

ErrorAn optional phone or zip field shows the pattern error when left empty

Short answer

Three things break matches in practice. An optional field fails on an empty string unless you set excludeEmptyString. A required() check fires first on empty strings, so its message shows instead of the pattern message. And a regex with the g flag keeps state between calls and alternates results. Check these before changing the pattern.

  • Applies to yup 1.x, React 19
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Test the schema outside React with the exact value that fails. If it fails there too, the schema is the problem, not the form library.

    console.log(await schema.isValid(''));
    console.log(await schema.isValid('0300123456'));
    console.log(await schema.isValid('0300123456'));
  2. 2Match what you see, then jump to its fix

    1. 1Fails only when the field is empty or clearedAn optional field is empty and the regex does not allow emptyFix
    2. 2An empty value shows the required message, not the pattern messageA required field is empty but you expected a different messageFix
    3. 3The same valid value alternates between passing and failingThe regex has the g flag and keeps state between testsFix

What does the error look like?

  • An optional phone or zip field shows the pattern error when left empty
  • The same valid value passes, then fails on the next validation
  • An empty field shows the required message instead of the pattern message

Cause 1 of 3

An optional field is empty and the regex does not allow empty

1Check

Most patterns need at least one character, so an empty string fails them. The field is optional, but matches still runs on ''.

grep -rn "matches(" src/

2Fix

Pass excludeEmptyString: true. The regex test is skipped for empty strings, so the pattern stays unchanged.

const schema = yup.string().matches(/^[0-9]{10}$/, {
  message: 'Enter 10 digits',
  excludeEmptyString: true,
});

3Verify

isValid('') is true, and isValid('123') is false.

console.log(await schema.isValid(''));
console.log(await schema.isValid('123'));

Confirmed by raw.githubusercontent.com

Did this fix it?

Cause 2 of 3

A required field is empty but you expected a different message

1Check

For strings, required() treats an empty string as missing, so the required error comes first for an empty value.

grep -rn "required(" src/

2Fix

Give required() its own message so the two errors read correctly, and keep the pattern message on matches. If the field is optional, drop required() and use excludeEmptyString instead.

yup.string()
  .required('Phone is required')
  .matches(/^[0-9]{10}$/, { message: 'Enter 10 digits' });

3Verify

Submit empty, then a bad value; each shows its own text.

npm test

Confirmed by raw.githubusercontent.com

Did this fix it?

Cause 3 of 3

The regex has the g flag and keeps state between tests

1Check

A regex with g or y keeps lastIndex between test() calls, and lastIndex does not reset while test() returns true, even for a different string. A shared regex literal reused by a schema is affected.

grep -rnE "matches\(/.*/[a-z]*g" src/

2Fix

Remove the g flag from validation patterns; a validation test never needs it.

// before
yup.string().matches(/^[a-z]+$/g, { message: 'letters only' });
// after
yup.string().matches(/^[a-z]+$/, { message: 'letters only' });

3Verify

Validate the same good value several times; it passes every time.

for (let i = 0; i < 3; i++) console.log(await schema.isValid('abc'));

Confirmed by developer.mozilla.org

Did this fix it?

How do I stop it coming back?

  • Unit-test each schema with empty, valid and invalid values.
  • Never use the g flag in a regex used for validation.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.