Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

class-validator rejects null or an empty string on an optional field

ErrorAn optional field fails validation when the client sends an empty string

Short answer

IsOptional only skips validators when the value is null or undefined. An empty string is a real value, so every other decorator on the field still runs and fails. Use ValidateIf with your own condition to skip validation for empty strings, and remember that IsNotEmpty rejects '', null and undefined.

  • Applies to NestJS 10, NestJS 11, class-validator 0.14, Node.js 22
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Send the exact payload that fails and compare it with the decorators on the field. The first message tells you which decorator rejected the value.

    curl -s -X POST http://localhost:3000/users \
      -H 'Content-Type: application/json' \
      -d '{"email":"","nickname":null}'
  2. 2Match what you see, then jump to its fix

    1. 1The field is marked IsOptional, the client sends an empty string and still gets a format errorAn empty string reaches the other decoratorsFix
    2. 2A not-empty message for null, undefined or an empty stringA field you meant to allow as empty is marked IsNotEmptyFix

What does the error look like?

  • An optional field fails validation when the client sends an empty string
  • A field that may be null is rejected with a validation message
  • A required-looking field says it should not be empty for null, undefined or an empty string

Cause 1 of 2

An empty string reaches the other decorators

1Check

class-validator describes IsOptional as ignoring all validators when the value is null or undefined. An empty string is neither.

grep -n -B1 -A3 "IsOptional" src/users/dto/*.ts

2Fix

Replace IsOptional with ValidateIf and say what counts as absent. When the condition is false, all validation decorators on the property are ignored.

import { IsEmail, ValidateIf } from 'class-validator'

export class CreateUserDto {
  @ValidateIf((o) => o.email !== '' && o.email != null)
  @IsEmail()
  email?: string | null
}

3Verify

Post the same body with an empty string, with null, and with a real email.

curl -s -X POST http://localhost:3000/users -H 'Content-Type: application/json' -d '{"email":""}'
curl -s -X POST http://localhost:3000/users -H 'Content-Type: application/json' -d '{"email":"a@example.com"}'

Confirmed by github.com

Did this fix it?

Cause 2 of 2

A field you meant to allow as empty is marked IsNotEmpty

1Check

IsNotEmpty checks that the value is not '', null or undefined, so all three are rejected.

grep -rn "IsNotEmpty" src

2Fix

If the field may be empty, remove IsNotEmpty and use the ValidateIf pattern above. Keep IsNotEmpty only on required fields.

export class UpdateProfileDto {
  @IsNotEmpty()
  username: string

  @ValidateIf((o) => o.bio != null)
  @IsString()
  bio?: string | null
}

3Verify

Send a body with bio set to null; it should pass, while an empty username should still fail.

curl -s -X PATCH http://localhost:3000/profile -H 'Content-Type: application/json' -d '{"username":"maaz","bio":null}'

Confirmed by github.com

Did this fix it?

How do I stop it coming back?

  • Decide for each optional field whether null, undefined and an empty string mean the same thing, and write that rule once in the DTO.
  • Add a unit test per DTO with the three payloads: missing, null, empty string.

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

Back end

NestJS GraphQL cannot work out the output type of a field or query

Cannot determine a GraphQL output type for the "<name>". Make sure your class is decorated with an appropriate decorator.

In code-first mode Nest reads TypeScript types through decorators, and arrays, promises and unions disappear at runtime.

2 causes, each with a fix

Back end

IntelliJ IDEA breakpoints are ignored in a NestJS app

No 'Debugger listening' line appears when the NestJS app starts

IntelliJ can only debug a NestJS app when the Node.js process runs with the inspector on and the IDE attaches to its port.

4 causes, each with a fix

Next step

Want this handled for good?

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