# ParseUUIDPipeOptions

**Kind:** Interface

**Source:** [`packages/common/pipes/parse-uuid.pipe.ts`](https://github.com/nestjs/nest/blob/master/packages/common/pipes/parse-uuid.pipe.ts#L17)

**Part of:** [Common](subsystem-packages-common)

`ParseUUIDPipeOptions` configures the behavior of NestJS's `ParseUUIDPipe`, which validates incoming values as UUIDs. It lets callers restrict accepted UUID versions, customize validation errors, provide a custom exception factory, and allow optional values to bypass validation.

## Properties

| Property | Type |
|---|---|
| `version` | `'3' | '4' | '5' | '7'` |
| `errorHttpStatusCode` | `ErrorHttpStatusCode` |
| `exceptionFactory` | `(errors: string) => any` |
| `optional` | `boolean` |

## Diagram

```mermaid
graph LR
  A[Incoming route value] --> B[ParseUUIDPipe]
  B --> C{Value is optional<br/>and empty?}
  C -->|Yes| D[Return value unchanged]
  C -->|No| E{Valid UUID?}
  E -->|Yes| F[Return validated UUID]
  E -->|No| G[Create validation exception]

  H[ParseUUIDPipeOptions] --> B
  H --> I[version: 3 | 4 | 5 | 7]
  H --> J[optional: boolean]
  H --> K[errorHttpStatusCode]
  H --> L[exceptionFactory]
  K --> G
  L --> G
```

## Usage

```ts
import {
  BadRequestException,
  ParseUUIDPipe,
} from '@nestjs/common';

const uuidPipe = new ParseUUIDPipe({
  version: '4',
  optional: false,
  exceptionFactory: (errors) =>
    new BadRequestException({
      message: 'Invalid user identifier',
      errors,
    }),
});

// Example controller usage
@Get(':id')
findOne(
  @Param('id', uuidPipe) id: string,
) {
  return this.usersService.findOne(id);
}
```

## AI Coding Instructions

- Use `version` to enforce the UUID format expected by the API, such as `'4'` for randomly generated identifiers.
- Set `optional: true` only for parameters that may legitimately be absent; valid non-empty values must still be UUIDs.
- Prefer `exceptionFactory` when the application requires a shared or custom error response format.
- Use `errorHttpStatusCode` for standard HTTP error customization when a custom exception body is unnecessary.
- Apply `ParseUUIDPipe` at controller boundaries (`@Param`, `@Query`, or `@Body`) before passing identifiers to services or repositories.

## How it works

## Type

`ParseUUIDPipeOptions` is the optional configuration interface accepted by `ParseUUIDPipe`’s constructor. The pipe stores these options and reads `version`, `exceptionFactory`, `errorHttpStatusCode`, and `optional` during construction or transformation. [`packages/common/pipes/parse-uuid.pipe.ts:17-38`](packages/common/pipes/parse-uuid.pipe.ts#L17-L38) [`packages/common/pipes/parse-uuid.pipe.ts:59-71`](packages/common/pipes/parse-uuid.pipe.ts#L59-L71)

## Members

- `version?: '3' | '4' | '5' | '7'` selects the UUID version pattern checked by the pipe. If omitted, the pipe checks against its general UUID pattern instead. [`packages/common/pipes/parse-uuid.pipe.ts:19-21`](packages/common/pipes/parse-uuid.pipe.ts#L19-L21) [`packages/common/pipes/parse-uuid.pipe.ts:67`](packages/common/pipes/parse-uuid.pipe.ts#L67) [`packages/common/pipes/parse-uuid.pipe.ts:77`](packages/common/pipes/parse-uuid.pipe.ts#L77) [`packages/common/pipes/parse-uuid.pipe.ts:87-92`](packages/common/pipes/parse-uuid.pipe.ts#L87-L92)

- `errorHttpStatusCode?: ErrorHttpStatusCode` selects the status-specific exception class used when no `exceptionFactory` is supplied; it defaults to `HttpStatus.BAD_REQUEST` (`400`). [`packages/common/pipes/parse-uuid.pipe.ts:23-25`](packages/common/pipes/parse-uuid.pipe.ts#L23-L25) [`packages/common/pipes/parse-uuid.pipe.ts:61-70`](packages/common/pipes/parse-uuid.pipe.ts#L61-L70) [`packages/common/enums/http-status.enum.ts:26`](packages/common/enums/http-status.enum.ts#L26) The `ErrorHttpStatusCode` type is limited to the status codes mapped in `HttpErrorByCode`, including bad request, unauthorized, forbidden, not found, conflict, several gateway/server errors, and others listed in its union. [`packages/common/utils/http-error-by-code.util.ts:27-48`](packages/common/utils/http-error-by-code.util.ts#L27-L48) [`packages/common/utils/http-error-by-code.util.ts:50-72`](packages/common/utils/http-error-by-code.util.ts#L50-L72)

- `exceptionFactory?: (errors: string) => any` replaces the default exception creation function. On invalid input, the pipe calls this function with either `"The value passed as UUID is not a string"` or a version-aware `"Validation failed (uuid ... is expected)"` message, then throws its return value. [`packages/common/pipes/parse-uuid.pipe.ts:27-32`](packages/common/pipes/parse-uuid.pipe.ts#L27-L32) [`packages/common/pipes/parse-uuid.pipe.ts:68-70`](packages/common/pipes/parse-uuid.pipe.ts#L68-L70) [`packages/common/pipes/parse-uuid.pipe.ts:77-82`](packages/common/pipes/parse-uuid.pipe.ts#L77-L82) [`packages/common/pipes/parse-uuid.pipe.ts:87-90`](packages/common/pipes/parse-uuid.pipe.ts#L87-L90)

- `optional?: boolean` changes handling only for `null` and `undefined`: when it is truthy, `transform()` returns either value unchanged without UUID checking. [`packages/common/pipes/parse-uuid.pipe.ts:33-37`](packages/common/pipes/parse-uuid.pipe.ts#L33-L37) [`packages/common/pipes/parse-uuid.pipe.ts:73-76`](packages/common/pipes/parse-uuid.pipe.ts#L73-L76) [`packages/common/utils/shared.utils.ts:48-49`](packages/common/utils/shared.utils.ts#L48-L49)

## Validation behavior controlled by the options

The accepted UUID patterns require hyphenated hexadecimal text with `8-4-4-4-12` groups. Version-specific patterns require `3`, `4`, `5`, or `7` at the beginning of the third group; versions 4, 5, and 7 also require `8`, `9`, `A`, or `B` at the beginning of the fourth group. Matching is case-insensitive. [`packages/common/pipes/parse-uuid.pipe.ts:49-55`](packages/common/pipes/parse-uuid.pipe.ts#L49-L55)

Except for the `optional` null/undefined path, a value must be a string before pattern matching. Non-string values cause the configured exception factory’s result to be thrown. [`packages/common/pipes/parse-uuid.pipe.ts:73-84`](packages/common/pipes/parse-uuid.pipe.ts#L73-L84) [`packages/common/pipes/parse-uuid.pipe.ts:87-92`](packages/common/pipes/parse-uuid.pipe.ts#L87-L92) [`packages/common/utils/shared.utils.ts:45`](packages/common/utils/shared.utils.ts#L45)