@lenne.tech/nest-server 11.42.15 → 11.42.16

package/docs/REQUEST-LIFECYCLE.md

@@ -107,6 +107,7 @@ JWT-based authentication for existing projects:
 | **Security Check Interceptor** | Calls `securityCheck()` + removes secret fields |
 | **Response Filter Interceptor** | Enforces `@Restricted()` field-level access |
 | **Translation Interceptor** | Applies `_translations` based on `Accept-Language` |
+| **CastError Filter** | `MongooseCastErrorFilter` (`APP_FILTER`, 11.42.16): a malformed id from a route parameter answers 404, one from the query string or an update/filter body 400, instead of an unhandled 500 (a create body raises `ValidationError` and stays a 500); a cast failure on a value the request does not contain stays a 500. See "Malformed ids: 404 / 400, not 500" below |
 | **Secret Fields Removal** | Configurable fallback removal of password, tokens, etc. |
 | **RequestContext** | `AsyncLocalStorage`-based context for current user in Mongoose hooks. `fromRequest` (11.42.0) marks a context created for a CLIENT operation (HTTP middleware, GraphQL WebSocket), so service-level checks such as `assertTenantRole()` tell an anonymous request apart from system work |
 | **Query Complexity** | GraphQL query complexity analysis to prevent DoS |
@@ -1215,6 +1216,33 @@ throw accessDeniedException(currentUser);
 See `src/core/common/exceptions/access-denied.exception.ts` and
 `migration-guides/11.27.7-to-11.28.0.md`.
 
+### Malformed ids: 404 / 400, not 500 (v11.42.16+)
+
+A malformed id reaches Mongoose, which throws `mongoose.Error.CastError`. That is not an
+`HttpException`, so it escapes `HttpExceptionLogFilter` (`@Catch(HttpException)`), and Nest used to
+answer **500** for what is simply "this resource does not exist". `CoreModule` registers
+`MongooseCastErrorFilter` as `APP_FILTER`; it decides by where the failing value came from:
+
+| Value of the failed cast | REST | GraphQL |
+|--------------------------|------|---------|
+| a route parameter (`GET /users/not-an-id`) / a top-level argument (`getUser(id: …)`) | **404** `ErrorCode.RESOURCE_NOT_FOUND` | same |
+| the query string or the body / nested in an input object | **400** `ErrorCode.INVALID_FIELD_FORMAT [<path>]` | same |
+| not in the request — a broken stored id, a value computed by server code | **500**, Nest's own body and log line | unchanged (Nest rethrows) |
+
+The third row is deliberate: that cast failure is a data or code defect, and answering it as a client
+error would hide it from monitoring. The Mongoose message never reaches the client — it names the
+model. Opt out with `security.mongooseCastErrorFilter: false`.
+
+Mongoose throws `CastError` only while casting a **query or an update** — `findById`, filters,
+`findByIdAndUpdate` / `updateOne` (the path `CrudService.update()` takes). Two neighbours are not
+covered and stay a 500:
+
+- a malformed id in a document being **created or saved** (`save()`, `Model.create()`, `insertMany()`
+  — the path `CrudService.create()` takes) arrives as a `ValidationError` wrapping the CastError;
+  validate reference ids in the input (`validator: () => [IsMongoId()]` on the `@UnifiedField`);
+- a `BSONError` from `new Types.ObjectId(bad)` in service code carries no value to classify; validate
+  such ids in the service, as `CoreFileService.isMalformedFileId()` does.
+
 ### Depth-Based Optimization (v11.23.0+)
 
 When `process()` is called from within another `process()` call (service cascades like A.create → B.create → C.create), steps 4–6 are **conditionally skipped** on inner calls to avoid redundant work:
@@ -1643,6 +1671,7 @@ All security features are configured in `config.env.ts` under the `security` key
 | `security.checkSecurityInterceptor` | `boolean \| object` | `true` | Enable securityCheck() calls |
 | `security.mapAndValidatePipe` | `boolean \| object` | `true` | Enable input validation |
 | `security.mapAndValidatePipe.nonWhitelistedFields` | `'strip' \| 'error' \| false` | `'strip'` | Whitelist behavior |
+| `security.mongooseCastErrorFilter` | `boolean` | `true` | Malformed request ids answer 404 / 400 instead of 500 |
 
 ### Safety Net — Mongoose Plugins
 

package/docs/security-overrides.md

@@ -64,13 +64,14 @@ overrides:
   'multer@>=2.0.0 <2.4.0': '2.4.0'
 
   # @nestjs/graphql 13.4.5 exact-pins @graphql-tools/utils@12.0.0 — GHSA-7mx3-vvmw-hjmv (high, patched >=12.0.1).
-  # Target the newest 12.x, so the caret requesters (@graphql-tools/schema / merge) are not held back.
+  # Target the newest 12.x, so the caret requesters (@graphql-tools/schema / merge) are not held back —
+  # @graphql-tools/schema 10.1.5 requests ^12.1.0, so a lower target leaves a second copy in the tree.
   # 12.0.2+ requires Node >=22.15 via @whatwg-node/promise-helpers@2 — the floor this framework declares
   # since 11.42.10. On an older Node, take 12.0.1 instead.
   # Does NOT reach a utils 11.x pulled in by an older @graphql-tools/schema 10.0.x — refresh that one instead:
   #   pnpm update --depth Infinity @graphql-tools/schema @graphql-tools/merge
   # Remove once @nestjs/graphql pins >=12.0.1 in the major you use.
-  '@graphql-tools/utils@>=12.0.0 <12.0.3': '12.0.3'
+  '@graphql-tools/utils@>=12.0.0 <12.1.0': '12.1.0'
 ```
 
 ### Retired: `@hono/node-server` (removed 2026-08-22, nest-server 11.36.1)

package/migration-guides/11.42.15-to-11.42.16.md

@@ -0,0 +1,114 @@
+# Migration Guide: 11.42.15 → 11.42.16
+
+## Overview
+
+| Category             | Details                                                                                                  |
+| -------------------- | -------------------------------------------------------------------------------------------------------- |
+| **Bugfixes**         | A malformed id in a route parameter answers **404** instead of **500**; one in the query string or an update body **400** (§1) |
+| **New Features**     | `MongooseCastErrorFilter`, registered automatically; opt-out `security.mongooseCastErrorFilter: false` (§1) |
+| **Framework API**    | New exports: `MongooseCastErrorFilter`, `classifyHttpCastError()`, `classifyGraphQlCastError()`, `castErrorCandidates()`, `containsCastValue()`, type `CastErrorOrigin`. No changed signatures |
+| **Dependencies**     | Development tooling only: `vitest` / `@vitest/coverage-v8` 4.1.11 → 4.1.12 (security, §2), `oxfmt` 0.72.0 → 0.73.0; override `@graphql-tools/utils` → 12.1.0 (§2). Runtime dependencies and peer ranges unchanged |
+| **Breaking Changes** | None. Status codes change from 500 to 404 / 400 for requests that were already failing (§1)              |
+| **Migration Effort** | None for most projects. Check tests or clients that expected a 500 for a malformed id (§1)               |
+
+## Quick Migration
+
+```bash
+pnpm update @lenne.tech/nest-server
+```
+
+Vendor-mode projects pick it up with the core update. No code or configuration change is required — the filter is
+registered by `CoreModule`, so neither `main.ts` nor test setups built with `Test.createTestingModule()` need a new
+line.
+
+## 1. Malformed ids answer 404 / 400 instead of 500
+
+A malformed id in a route parameter (`GET /users/not-an-id`, `/ai/connections/abc`) reached Mongoose, which throws
+`mongoose.Error.CastError`. That is not an `HttpException`, so it escaped `HttpExceptionLogFilter`
+(`@Catch(HttpException)`) and Nest answered **500 Internal server error** for what is simply "this resource does not
+exist". In a typical project that affected every `:id` route, including the framework's own `/users/:id` and the AI
+module's routes.
+
+`CoreModule` now registers `MongooseCastErrorFilter` as `APP_FILTER`. It decides by where the value that failed to
+cast came from:
+
+| Value of the failed cast | REST | GraphQL |
+| ------------------------ | ---- | ------- |
+| a route parameter / a top-level argument (`getUser(id: …)`) | **404** `#LTNS_0400: Resource not found` | same |
+| the query string or an update / filter body / a value nested in an input | **400** `#LTNS_0302: Invalid field format [<path>]` | same |
+| not in the request (a broken stored id, a value computed by server code) | **500**, unchanged — Nest's body, logged as an error | unchanged |
+
+The third row is deliberate: a cast failure on a value the request does not contain is a data or code defect, and
+answering it as a client error would hide it from monitoring. The Mongoose message is never sent to the client — it
+names the model. REST bodies have the same shape as every other error `HttpExceptionLogFilter` answers.
+
+**What to check:**
+
+- **A test or client expected 500 for a malformed id:** it now gets 404 (route parameter) or 400 (query / body).
+  A well-formed id that matches nothing keeps answering 404 as before, so 404 now means the same for both.
+- **A project filter already handled `CastError`:** a catch-all filter registered with `app.useGlobalFilters()` is
+  consulted before this one and keeps winning. One registered as `APP_FILTER` in the project's root module is
+  consulted after it — set `security.mongooseCastErrorFilter: false` if your own filter must see every `CastError`
+  (for example a Sentry filter that reports them).
+- **You want the previous behaviour:** `security.mongooseCastErrorFilter: false` restores the 500.
+
+**Not covered — both stay a 500:**
+
+- A malformed id in a document being **created** (`save()`, `Model.create()`, `insertMany()` — the path
+  `CrudService.create()` takes). Mongoose reports that as a `ValidationError` wrapping the `CastError`. Validate
+  reference ids in the input instead:
+
+  ```typescript
+  import { IsMongoId } from 'class-validator';
+
+  @UnifiedField({ isOptional: true, type: () => String, validator: () => [IsMongoId()] })
+  owner?: string = undefined;
+  ```
+
+- A `BSONError` from `new Types.ObjectId(bad)` in service code. It carries no value to classify; check the id
+  before converting it, as `CoreFileService.isMalformedFileId()` does.
+
+## 2. Development tooling and the `@graphql-tools/utils` override
+
+Nothing here reaches the published package's runtime dependencies. Worth mirroring in your own project:
+
+- **`vitest` and `@vitest/coverage-v8` 4.1.12** fix two `@vitest/mocker` advisories published on 2026-10-16
+  (GHSA-qxg6-89mg-rqv8, GHSA-xp26-3454-mjgp, both medium). Development tooling only. `pnpm audit` may not list them
+  yet, so raise both together without waiting for it: `@vitest/coverage-v8` peer-requires the exact vitest version.
+- **`@graphql-tools/utils` override:** if your project carries its own entry for GHSA-7mx3-vvmw-hjmv (overrides do
+  not reach consumers, so many do), raise it:
+
+  ```yaml
+  # pnpm-workspace.yaml
+  overrides:
+    '@graphql-tools/utils@>=12.0.0 <12.1.0': '12.1.0'   # was: '<12.0.3': '12.0.3' / '<12.0.4': '12.0.4'
+  ```
+
+  The old target still clears the advisory, but `@graphql-tools/schema` 10.1.5 (pulled in by `@apollo/server`)
+  requests `^12.1.0`, so a lower target leaves two copies of `@graphql-tools/utils` in the tree.
+  See [`docs/security-overrides.md`](../docs/security-overrides.md).
+
+## Compatibility Notes
+
+| Pattern | Status |
+| ------- | ------ |
+| `main.ts` with `app.useGlobalFilters(new HttpExceptionLogFilter())` | Unchanged; both filters coexist (they catch different classes) |
+| A project catch-all filter via `app.useGlobalFilters()` | Unchanged; it still sees every `CastError` |
+| A project catch-all filter as `APP_FILTER` in the root module | No longer sees `CastError` — opt out if it must (§1) |
+| Tests built with `Test.createTestingModule({ imports: [ServerModule] })` | Get the filter automatically |
+| `security.mongooseCastErrorFilter: false` | Previous behaviour (500) |
+
+## Troubleshooting
+
+**A malformed id still answers 500**
+Check where it fails. A create path raises `ValidationError` (see "Not covered" above); a `new Types.ObjectId(bad)` in
+service code raises `BSONError`; a value from a header or from stored data is not in the request and stays a 500 on
+purpose. The server log names the cast at debug level (`MongooseCastErrorFilter`) when the filter answered 404 / 400.
+
+**A 400 names a field the client did not send**
+The path in brackets is the schema path Mongoose failed to cast. For a filter on `id` it reads `[_id]`.
+
+## Module Documentation
+
+- [Request lifecycle](../docs/REQUEST-LIFECYCLE.md) — "Malformed ids: 404 / 400, not 500"
+- Implementation: `src/core/common/filters/mongoose-cast-error.filter.ts`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "11.42.15",
+  "version": "11.42.16",
   "description": "Modern, fast, powerful Node.js web framework in TypeScript based on Nest with a GraphQL API and a connection to MongoDB (or other databases).",
   "keywords": [
     "node",
@@ -202,7 +202,7 @@
     "@types/multer": "2.3.0",
     "@types/node": "26.6.5",
     "@types/passport": "1.0.17",
-    "@vitest/coverage-v8": "4.1.11",
+    "@vitest/coverage-v8": "4.1.12",
     "better-auth": "1.7.7",
     "bullmq": "6.3.15",
     "cross-env": "10.1.0",
@@ -210,7 +210,7 @@
     "nodemon": "3.1.14",
     "npm-watch": "0.13.0",
     "otpauth": "9.5.2",
-    "oxfmt": "0.72.0",
+    "oxfmt": "0.73.0",
     "oxlint": "1.88.0",
     "rimraf": "6.1.3",
     "smtp-server": "3.19.23",
@@ -222,7 +222,7 @@
     "unplugin-swc": "2.0.0",
     "vite": "8.3.4",
     "vite-plugin-node": "8.0.0",
-    "vitest": "4.1.11"
+    "vitest": "4.1.12"
   },
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/core/common/filters/mongoose-cast-error.filter.ts

@@ -0,0 +1,310 @@
+import {
+  ArgumentsHost,
+  BadRequestException,
+  Catch,
+  ExceptionFilter,
+  HttpException,
+  HttpStatus,
+  Logger,
+  NotFoundException,
+} from '@nestjs/common';
+import { Error as MongooseError } from 'mongoose';
+
+import { ErrorCode } from '../../modules/error-code/error-codes';
+
+import type { GqlContextType } from '@nestjs/graphql';
+import type { Request, Response } from 'express';
+
+/**
+ * Where the value of a failed Mongoose cast came from — and therefore who is at fault.
+ *
+ * - `identifier`: it names the resource the request addresses — a route parameter, or a top-level
+ *   GraphQL argument. A malformed identifier names nothing, so it is answered like an unknown one: 404.
+ * - `input`: the client sent it as data — query string, body, or nested inside a GraphQL input: 400.
+ * - `server`: the request does not contain it. It came from stored data or from server code, which is
+ *   a data or code defect and stays a 500, so monitoring keeps seeing it.
+ */
+export type CastErrorOrigin = 'identifier' | 'input' | 'server';
+
+/**
+ * Bounds for walking request data. They keep error handling cheap and terminating for a deeply nested,
+ * very wide or self-referencing structure — the body parser's size limit alone does not: a project may
+ * raise it, and a few megabytes of `[0,0,0,…]` are a million nodes. What the budget cannot reach is not
+ * matched, which answers `server` (a 500), the status quo — never a client error.
+ */
+const MAX_WALK_DEPTH = 32;
+const MAX_WALK_NODES = 10_000;
+
+type Primitive = bigint | boolean | number | string;
+
+function isPrimitive(value: unknown): value is Primitive {
+  return (
+    typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean' || typeof value === 'bigint'
+  );
+}
+
+/**
+ * The strings a CastError's `value` stands for.
+ *
+ * A primitive stands for itself, an array (the `$in` shape) for each of its primitive elements.
+ * Anything else yields nothing: the strings inside an object cast as a whole (a subdocument, a whole
+ * array of them) are not what failed, and matching them against the request would relabel a server
+ * defect as a client error whenever one of them happens to appear in the body.
+ */
+export function castErrorCandidates(value: unknown): string[] {
+  if (isPrimitive(value)) {
+    return [String(value)];
+  }
+  if (Array.isArray(value)) {
+    return value.filter(isPrimitive).map((item) => String(item));
+  }
+  return [];
+}
+
+/**
+ * The children of an array or object, or `undefined` when there are more than `room` of them.
+ *
+ * Never collects more than `room` entries: an object is read key by key rather than through
+ * `Object.values()`, which would first copy every value of a million-key object.
+ */
+function boundedChildren(value: object, room: number): readonly unknown[] | undefined {
+  if (Array.isArray(value)) {
+    return value.length > room ? undefined : value;
+  }
+  const children: unknown[] = [];
+  // Own enumerable keys only, as Object.values — also for the null-prototype objects Express's query
+  // parser and graphql-js produce, which is why hasOwnProperty is borrowed rather than called
+  for (const key in value) {
+    if (!Object.prototype.hasOwnProperty.call(value, key)) {
+      continue;
+    }
+    if (children.length >= room) {
+      return undefined;
+    }
+    children.push((value as Record<string, unknown>)[key]);
+  }
+  return children;
+}
+
+/**
+ * Whether one of `candidates` occurs as a primitive anywhere in `source` (compared as strings, so a
+ * number in a JSON body matches the number Mongoose failed to cast). Depth- and size-bounded, and
+ * safe against cycles.
+ *
+ * The node budget is checked BEFORE a container's children are queued, not when they are visited: a
+ * container the remaining budget cannot hold is skipped as a whole. Queuing first and counting later
+ * let `{ ids: ['bad'], pad: [<a million zeros>] }` allocate a million stack entries and then give up
+ * before reaching `ids` — a 400 answered as a 500 after half a second of blocked event loop. Skipping
+ * (rather than queuing the first few) also leaves the budget to the oversized container's siblings.
+ */
+export function containsCastValue(source: unknown, candidates: readonly string[]): boolean {
+  if (!candidates.length) {
+    return false;
+  }
+  const wanted = new Set(candidates);
+  const seen = new Set<object>();
+  const stack: { depth: number; value: unknown }[] = [{ depth: 0, value: source }];
+  let nodes = 0;
+  for (let item = stack.pop(); item; item = stack.pop()) {
+    const { depth, value } = item;
+    // Unreachable while boundedChildren() keeps the invariant below; kept so that a regression there
+    // degrades to a 500 instead of an unbounded walk
+    if (++nodes > MAX_WALK_NODES) {
+      return false;
+    }
+    if (isPrimitive(value)) {
+      if (wanted.has(String(value))) {
+        return true;
+      }
+      continue;
+    }
+    if (!value || typeof value !== 'object' || depth >= MAX_WALK_DEPTH || ArrayBuffer.isView(value)) {
+      continue;
+    }
+    if (seen.has(value)) {
+      continue;
+    }
+    seen.add(value);
+    // nodes + stack.length never exceeds MAX_WALK_NODES: only what the budget can still hold is queued
+    const children = boundedChildren(value, MAX_WALK_NODES - nodes - stack.length);
+    for (const child of children ?? []) {
+      stack.push({ depth: depth + 1, value: child });
+    }
+  }
+  return false;
+}
+
+/**
+ * Whether one of `candidates` is one of `values` itself, or an element of an array among them — the
+ * shape of route parameters (Express 5 wildcards are arrays) and of top-level GraphQL arguments.
+ */
+function isDirectValue(values: readonly unknown[], candidates: readonly string[]): boolean {
+  const wanted = new Set(candidates);
+  const matches = (value: unknown) => isPrimitive(value) && wanted.has(String(value));
+  // A list beyond the walk budget is not scanned here either — a GraphQL list argument is client-sized
+  return values.some((value) =>
+    Array.isArray(value) ? value.length <= MAX_WALK_NODES && value.some(matches) : matches(value),
+  );
+}
+
+/**
+ * Classify a CastError raised while handling a REST request.
+ *
+ * A value that is a route parameter is an `identifier`; one found anywhere in the query string or the
+ * body is `input`; anything else is `server`. The parameter check runs first, so `PATCH /x/:id` with the
+ * same malformed id in its body is still a 404.
+ */
+export function classifyHttpCastError(
+  value: unknown,
+  request: Partial<Pick<Request, 'body' | 'params' | 'query'>> | undefined,
+): CastErrorOrigin {
+  const candidates = castErrorCandidates(value);
+  if (!candidates.length || !request) {
+    return 'server';
+  }
+  if (isDirectValue(Object.values(request.params ?? {}), candidates)) {
+    return 'identifier';
+  }
+  if (containsCastValue(request.query, candidates) || containsCastValue(request.body, candidates)) {
+    return 'input';
+  }
+  return 'server';
+}
+
+/**
+ * Classify a CastError raised while executing a GraphQL field.
+ *
+ * The GraphQL counterpart of a route parameter is a top-level scalar argument (`getUser(id: …)`), and
+ * of a body a value nested inside an input object (`findUsers(filter: …)`, `updateUser(input: …)`).
+ */
+export function classifyGraphQlCastError(value: unknown, args: unknown): CastErrorOrigin {
+  const candidates = castErrorCandidates(value);
+  if (!candidates.length || !args || typeof args !== 'object') {
+    return 'server';
+  }
+  if (isDirectValue(Object.values(args), candidates)) {
+    return 'identifier';
+  }
+  if (containsCastValue(args, candidates)) {
+    return 'input';
+  }
+  return 'server';
+}
+
+/**
+ * Answers a Mongoose `CastError` caused by the CLIENT as a client error instead of a 500.
+ *
+ * A malformed id in a route parameter (`GET /users/not-an-id`) reaches Mongoose, which throws
+ * `CastError`. That is not an `HttpException`, so it escaped every `@Catch(HttpException)` filter and Nest
+ * answered **500 Internal server error** for what is simply "this resource does not exist".
+ *
+ * | Value of the failed cast | REST | GraphQL |
+ * |--------------------------|------|---------|
+ * | a route parameter / a top-level argument | 404 `ErrorCode.RESOURCE_NOT_FOUND` | same |
+ * | in the query string or the body / nested in an input | 400 `ErrorCode.INVALID_FIELD_FORMAT [path]` | same |
+ * | not in the request (stored data, server code) | 500, exactly as before, logged as an error | unchanged |
+ *
+ * The third row is deliberate: a broken id in stored data or a cast on a server-computed value is a
+ * defect, and relabelling it as a client error would hide it from monitoring.
+ *
+ * The Mongoose message is never sent: it names the model. Registered by `CoreModule` as `APP_FILTER`
+ * (opt out with `security.mongooseCastErrorFilter: false`), so `main.ts` and test setups need no change.
+ * A project's own catch-all filter registered via `app.useGlobalFilters()` is consulted first and wins.
+ *
+ * Only `CastError` is handled, and Mongoose raises it only while casting a QUERY or an UPDATE
+ * (filters, `findById`, `findByIdAndUpdate` / `updateOne` — the path `CrudService.update()` takes). Two
+ * neighbours stay a 500:
+ * - a malformed id in a document being CREATED or SAVED (`new Model().save()`, `Model.create()`,
+ *   `insertMany()` — the path `CrudService.create()` takes) arrives as a `ValidationError` wrapping the
+ *   CastError. Validate reference ids in the input instead (`validator: () => [IsMongoId()]` on the
+ *   `@UnifiedField`);
+ * - a `BSONError` from `new Types.ObjectId(bad)` in service code carries no value to classify; such code
+ *   should check the id itself (see `CoreFileService.isMalformedFileId()`).
+ */
+@Catch(MongooseError.CastError)
+export class MongooseCastErrorFilter implements ExceptionFilter {
+  protected static readonly logger = new Logger('MongooseCastErrorFilter');
+
+  /**
+   * The context Nest's own handler logs an unknown error under — so a cast failure that stays a 500 is
+   * logged exactly as before this filter existed, and monitoring matching that line keeps matching.
+   */
+  protected static readonly unknownErrorLogger = new Logger('ExceptionsHandler');
+
+  catch(exception: MongooseError.CastError, host: ArgumentsHost): HttpException | undefined {
+    const type = host.getType<GqlContextType>();
+    if (type === 'graphql') {
+      return this.catchGraphQl(exception, host);
+    }
+    if (type === 'http') {
+      this.catchHttp(exception, host);
+    }
+    // Any other transport: returning nothing hands the error back to its own exception handler
+    return undefined;
+  }
+
+  /**
+   * GraphQL: the returned exception becomes the field error. Returning nothing hands the error back to
+   * Nest's external exception handler, which logs and rethrows it — what happened before this filter.
+   */
+  protected catchGraphQl(exception: MongooseError.CastError, host: ArgumentsHost): HttpException | undefined {
+    const origin = classifyGraphQlCastError(exception.value, host.getArgByIndex(1));
+    if (origin === 'server') {
+      return undefined;
+    }
+    return this.toHttpException(exception, origin);
+  }
+
+  /**
+   * REST: a filter that matched must answer the request itself — Nest does not fall back to its own
+   * handler afterwards.
+   */
+  protected catchHttp(exception: MongooseError.CastError, host: ArgumentsHost): void {
+    const ctx = host.switchToHttp();
+    const response = ctx.getResponse<Response>();
+    const origin = classifyHttpCastError(exception.value, ctx.getRequest<Request>());
+    if (origin === 'server') {
+      this.replyAsUnknownError(exception, response);
+      return;
+    }
+    const httpException = this.toHttpException(exception, origin);
+    if (response.headersSent) {
+      response.end();
+      return;
+    }
+    // Same wire shape as HttpExceptionLogFilter, so a client sees one error format for every 4xx
+    response.status(httpException.getStatus()).json({ ...httpException });
+  }
+
+  /**
+   * The client error a request-supplied cast failure is answered with. The Mongoose message stays in
+   * the server log (debug level): it names the model, which is none of the client's business.
+   */
+  protected toHttpException(exception: MongooseError.CastError, origin: 'identifier' | 'input'): HttpException {
+    MongooseCastErrorFilter.logger.debug(
+      `Cast failed on a value from the request (${origin === 'identifier' ? 404 : 400}): ${exception.message}`,
+    );
+    if (origin === 'identifier') {
+      return new NotFoundException(ErrorCode.RESOURCE_NOT_FOUND);
+    }
+    return new BadRequestException(
+      exception.path ? `${ErrorCode.INVALID_FIELD_FORMAT} [${exception.path}]` : ErrorCode.INVALID_FIELD_FORMAT,
+    );
+  }
+
+  /**
+   * What Nest's `BaseExceptionFilter` does with an error it does not know: the generic 500 body, and
+   * the error object itself in the log — `logger.error(exception)`, the same call Nest 11 makes, so the
+   * line (and its JSON form under a JSON logger) is the one monitoring already sees.
+   */
+  protected replyAsUnknownError(exception: Error, response: Response): void {
+    if (response.headersSent) {
+      response.end();
+    } else {
+      response
+        .status(HttpStatus.INTERNAL_SERVER_ERROR)
+        .json({ statusCode: HttpStatus.INTERNAL_SERVER_ERROR, message: 'Internal server error' });
+    }
+    MongooseCastErrorFilter.unknownErrorLogger.error(exception);
+  }
+}

package/src/core/common/interfaces/server-options.interface.ts

@@ -3154,6 +3154,28 @@ export interface IServerOptions {
           nonWhitelistedFields?: 'strip' | 'error' | false;
         };
 
+    /**
+     * Answer a Mongoose `CastError` caused by the client as a client error instead of a 500.
+     * See @lenne.tech/nest-server/src/core/common/filters/mongoose-cast-error.filter.ts
+     *
+     * A malformed id in a route parameter (`GET /users/not-an-id`) answers 404
+     * (`ErrorCode.RESOURCE_NOT_FOUND`), one in the query string or the body 400
+     * (`ErrorCode.INVALID_FIELD_FORMAT`); GraphQL likewise for a top-level argument and a nested input.
+     * A failed cast on a value the request does not contain (stored data, server code) stays a 500.
+     *
+     * Covers casts Mongoose performs while running a query or an update (`findById`, filters,
+     * `findByIdAndUpdate`). A malformed id in a document being created (`save()`, `create()`,
+     * `insertMany()`) is a Mongoose `ValidationError` instead and stays a 500 — validate such ids in the
+     * input (`validator: () => [IsMongoId()]`).
+     *
+     * Registered by `CoreModule` as `APP_FILTER`. `false` restores the previous behaviour, in which every
+     * `CastError` answered 500.
+     *
+     * @default true
+     * @since 11.42.16
+     */
+    mongooseCastErrorFilter?: boolean;
+
     /**
      * Mongoose password hashing plugin - automatically hashes passwords on save/update
      * (save, findOneAndUpdate, updateOne, updateMany).

package/src/core.module.ts

@@ -8,13 +8,14 @@ import {
   NestModule,
   UnauthorizedException,
 } from '@nestjs/common';
-import { APP_INTERCEPTOR, APP_PIPE, DiscoveryModule } from '@nestjs/core';
+import { APP_FILTER, APP_INTERCEPTOR, APP_PIPE, DiscoveryModule } from '@nestjs/core';
 import { GraphQLModule } from '@nestjs/graphql';
 import { MongooseModule } from '@nestjs/mongoose';
 import type { Context } from 'graphql-ws';
 import graphqlUploadExpress = require('graphql-upload/graphqlUploadExpress.js');
 import mongoose from 'mongoose';
 
+import { MongooseCastErrorFilter } from './core/common/filters/mongoose-cast-error.filter';
 import { merge } from './core/common/helpers/config.helper';
 import { registerWsConnection } from './core/common/helpers/graphql-ws-connection.helper';
 import {
@@ -391,6 +392,17 @@ export class CoreModule implements NestModule {
       });
     }
 
+    // MongooseCastErrorFilter: a malformed id from the request answers 404 (route parameter) or 400
+    // (query/body) instead of escaping every @Catch(HttpException) filter as a 500. A cast failure on a
+    // value the request does not contain stays a 500. Registered here rather than in main.ts so that
+    // test setups built with Test.createTestingModule() get it too.
+    if (config.security?.mongooseCastErrorFilter !== false) {
+      providers.push({
+        provide: APP_FILTER,
+        useClass: MongooseCastErrorFilter,
+      });
+    }
+
     if (config.mongoose?.modelDocumentation) {
       providers.push(ModelDocService);
     }

package/src/index.ts

@@ -29,6 +29,7 @@ export * from './core/common/enums/role.enum';
 export * from './core/common/enums/sort-order.emum';
 export * from './core/common/exceptions/access-denied.exception';
 export * from './core/common/filters/http-exception-log.filter';
+export * from './core/common/filters/mongoose-cast-error.filter';
 export * from './core/common/helpers/common.helper';
 export * from './core/common/helpers/config.helper';
 export * from './core/common/helpers/content-disposition.helper';