nestjs/nest · error · Error

Version constraint should be a string or an array of strings

Error message

Version constraint should be a string or an array of strings.

What it means

Error "Version constraint should be a string or an array of strings." thrown in nestjs/nest.

Source

Thrown at packages/platform-fastify/adapters/fastify-adapter.ts:165

  private _isParserRegistered: boolean;
  private onRequestHook?: (
    request: TRequest,
    reply: TReply,
    done: (err?: Error) => void,
  ) => void | Promise<void>;
  private onResponseHook?: (
    request: TRequest,
    reply: TReply,
    done: (err?: Error) => void,
  ) => void | Promise<void>;
  private isMiddieRegistered: boolean;
  private pendingMiddlewares: Array<{ args: any[] }> = [];
  private versioningOptions?: VersioningOptions;
  private readonly versionConstraint = {
    name: 'version',
    validate(value: unknown) {
      if (!isString(value) && !Array.isArray(value)) {
        throw new Error(
          'Version constraint should be a string or an array of strings.',
        );
      }
    },
    storage() {
      const versions = new Map<string, unknown>();
      return {
        get(version: string | Array<string>) {
          if (Array.isArray(version)) {
            return versions.get(version.find(v => versions.has(v))!) || null;
          }
          return versions.get(version) || null;
        },
        set(versionOrVersions: string | Array<string>, store: unknown) {
          const storeVersionConstraint = (version: string) =>
            versions.set(version, store);
          if (Array.isArray(versionOrVersions))
            versionOrVersions.forEach(storeVersionConstraint);

View on GitHub (pinned to 6ec0e2783d)

Solutions

1. Set the route/controller version to a string (e.g. '1') or an array of strings (e.g. ['1','2']).
2. Do not pass numbers, objects, or undefined as the version constraint.
3. Use VERSION_NEUTRAL explicitly when a route should ignore versioning.

Example fix

@Controller({ path: 'cats', version: ['1', '2'] })
export class CatsController {}

When it happens

Trigger: Thrown at packages/platform-fastify/adapters/fastify-adapter.ts:165 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of nestjs/nest@6ec0e2783d (2026-08-03). Data as JSON: /data/errors/5e29405210b0403a.json. Report an issue: GitHub.