croco-dev · kang-heewon · Aug 8, 2026
diff --git a/.changeset/safe-graphql-body-limit-configuration.md b/.changeset/safe-graphql-body-limit-configuration.md
@@ -0,0 +1,6 @@
+---
+"@croco/problems-core": patch
+"@croco/transports-graphql": patch
+---
+
+Reject unsafe GraphQL request body limits during server initialization with the stable `transports-graphql/body-limit-invalid-configuration` Problem, while preserving an inclusive byte boundary for buffered and streamed requests.
diff --git a/docs/problem-code-registry.json b/docs/problem-code-registry.json
@@ -1,6 +1,6 @@
 {
   "version": "croco.problem-code-registry.v1",
-  "problemCount": 582,
+  "problemCount": 583,
   "problems": [
     {
       "code": "ACCESS_DENIED",
@@ -15217,6 +15217,36 @@
         }
       ]
     },
+    {
+      "code": "transports-graphql/body-limit-invalid-configuration",
+      "category": "InternalServerError",
+      "status": 500,
+      "title": "Internal Server Error",
+      "cookbookPath": "/reference/problem-recovery-cookbook/#transports-graphql-body-limit-invalid-configuration",
+      "recovery": {
+        "cause": "The GraphQL server was configured with an invalid request body byte boundary.",
+        "userAction": "Ask the operator to correct the service configuration before retrying.",
+        "operatorAction": "Set maxBodySizeBytes to a finite positive safe integer and restart the service.",
+        "retryability": "not-retryable",
+        "redactionPolicy": "operator-only",
+        "telemetry": {
+          "eventName": "croco.problem.error",
+          "severity": "error",
+          "attributes": ["problem.code", "problem.category", "problem.status"]
+        }
+      },
+      "lifecycle": {
+        "status": "active"
+      },
+      "sources": [
+        {
+          "file": "packages/transports-graphql/src/libs/problems/GraphQLTransportProblems.ts",
+          "line": 8,
+          "column": 5,
+          "kind": "problem-constructor"
+        }
+      ]
+    },
     {
       "code": "transports-graphql/request-body-aborted",
       "category": "BadRequest",
@@ -15241,7 +15271,7 @@
       "sources": [
         {
           "file": "packages/transports-graphql/src/libs/problems/GraphQLTransportProblems.ts",
-          "line": 47,
+          "line": 63,
           "column": 3,
           "kind": "problem-class"
         }
@@ -15271,7 +15301,7 @@
       "sources": [
         {
           "file": "packages/transports-graphql/src/libs/problems/GraphQLTransportProblems.ts",
-          "line": 33,
+          "line": 49,
           "column": 5,
           "kind": "problem-constructor"
         }
@@ -15301,7 +15331,7 @@
       "sources": [
         {
           "file": "packages/transports-graphql/src/libs/problems/GraphQLTransportProblems.ts",
-          "line": 4,
+          "line": 20,
           "column": 3,
           "kind": "problem-class"
         }
@@ -15331,7 +15361,7 @@
       "sources": [
         {
           "file": "packages/transports-graphql/src/libs/problems/GraphQLTransportProblems.ts",
-          "line": 16,
+          "line": 32,
           "column": 3,
           "kind": "problem-class"
         }
@@ -15361,7 +15391,7 @@
       "sources": [
         {
           "file": "packages/transports-graphql/src/libs/problems/GraphQLTransportProblems.ts",
-          "line": 24,
+          "line": 40,
           "column": 3,
           "kind": "problem-class"
         }

diff --git a/packages/docs/src/content/docs/en/reference/problem-recovery-cookbook.md b/packages/docs/src/content/docs/en/reference/problem-recovery-cookbook.md
@@ -7,7 +7,7 @@ description: Generated Croco Problem code registry with recovery and telemetry m
 
 > Generated by `pnpm problem-registry:write`. Do not edit this file by hand.
 
-This cookbook documents 582 public Croco Problem codes. The deterministic JSON registry is generated at `docs/problem-code-registry.json`, and generated client union types are emitted at `packages/problems-core/src/generated/problem-code-registry.ts`.
+This cookbook documents 583 public Croco Problem codes. The deterministic JSON registry is generated at `docs/problem-code-registry.json`, and generated client union types are emitted at `packages/problems-core/src/generated/problem-code-registry.ts`.
 
 ## Index
 
@@ -520,6 +520,7 @@ This cookbook documents 582 public Croco Problem codes. The deterministic JSON r
 | [`testing/transaction-context-not-active`](#testing-transaction-context-not-active)                                                   | InternalServerError   |    500 | conditional   | operator-only | active     |       1 |
 | [`TOKEN_LIMIT_EXCEEDED`](#token-limit-exceeded)                                                                                       | BadRequest            |    400 | not-retryable | public        | active     |       1 |
 | [`TOOL_EXECUTION_ERROR`](#tool-execution-error)                                                                                       | InternalServerError   |    500 | conditional   | operator-only | active     |       1 |
+| [`transports-graphql/body-limit-invalid-configuration`](#transports-graphql-body-limit-invalid-configuration)                         | InternalServerError   |    500 | not-retryable | operator-only | active     |       1 |
 | [`transports-graphql/request-body-aborted`](#transports-graphql-request-body-aborted)                                                 | BadRequest            |    400 | not-retryable | public        | active     |       1 |
 | [`transports-graphql/request-body-too-large`](#transports-graphql-request-body-too-large)                                             | PayloadTooLarge       |    413 | not-retryable | public        | active     |       1 |
 | [`transports-graphql/resolvers-not-configured`](#transports-graphql-resolvers-not-configured)                                         | InternalServerError   |    500 | conditional   | operator-only | active     |       1 |
@@ -9730,6 +9731,24 @@ Sources:
 
 - `packages/llm-core/src/libs/problems/LlmServiceProblem.ts:61:5` (problem-constructor)
 
+<a id="transports-graphql-body-limit-invalid-configuration"></a>
+
+## `transports-graphql/body-limit-invalid-configuration`
+
+- Category: `InternalServerError`
+- HTTP status: `500` Internal Server Error
+- Retryability: `not-retryable`
+- Redaction policy: `operator-only`
+- Lifecycle: `active`
+- Cause: The GraphQL server was configured with an invalid request body byte boundary.
+- User action: Ask the operator to correct the service configuration before retrying.
+- Operator action: Set maxBodySizeBytes to a finite positive safe integer and restart the service.
+- Telemetry: `croco.problem.error` (error) with `problem.code`, `problem.category`, `problem.status`
+
+Sources:
+
+- `packages/transports-graphql/src/libs/problems/GraphQLTransportProblems.ts:8:5` (problem-constructor)
+
 <a id="transports-graphql-request-body-aborted"></a>
 
 ## `transports-graphql/request-body-aborted`
@@ -9746,7 +9765,7 @@ Sources:
 
 Sources:
 
-- `packages/transports-graphql/src/libs/problems/GraphQLTransportProblems.ts:47:3` (problem-class)
+- `packages/transports-graphql/src/libs/problems/GraphQLTransportProblems.ts:63:3` (problem-class)
 
 <a id="transports-graphql-request-body-too-large"></a>
 
@@ -9764,7 +9783,7 @@ Sources:
 
 Sources:
 
-- `packages/transports-graphql/src/libs/problems/GraphQLTransportProblems.ts:33:5` (problem-constructor)
+- `packages/transports-graphql/src/libs/problems/GraphQLTransportProblems.ts:49:5` (problem-constructor)
 
 <a id="transports-graphql-resolvers-not-configured"></a>
 
@@ -9782,7 +9801,7 @@ Sources:
 
 Sources:
 
-- `packages/transports-graphql/src/libs/problems/GraphQLTransportProblems.ts:4:3` (problem-class)
+- `packages/transports-graphql/src/libs/problems/GraphQLTransportProblems.ts:20:3` (problem-class)
 
 <a id="transports-graphql-schema-not-configured"></a>
 
@@ -9800,7 +9819,7 @@ Sources:
 
 Sources:
 
-- `packages/transports-graphql/src/libs/problems/GraphQLTransportProblems.ts:16:3` (problem-class)
+- `packages/transports-graphql/src/libs/problems/GraphQLTransportProblems.ts:32:3` (problem-class)
 
 <a id="transports-graphql-server-not-initialized"></a>
 
@@ -9818,7 +9837,7 @@ Sources:
 
 Sources:
 
-- `packages/transports-graphql/src/libs/problems/GraphQLTransportProblems.ts:24:3` (problem-class)
+- `packages/transports-graphql/src/libs/problems/GraphQLTransportProblems.ts:40:3` (problem-class)
 
 <a id="transports-http-body-limit-invalid-configuration"></a>
 

diff --git a/packages/problems-core/src/generated/problem-code-registry.ts b/packages/problems-core/src/generated/problem-code-registry.ts
@@ -3,7 +3,7 @@ import type { ProblemCodeRegistry } from "../libs/ProblemRegistry";
 
 export const CROCO_PROBLEM_CODE_REGISTRY = {
   version: "croco.problem-code-registry.v1",
-  problemCount: 582,
+  problemCount: 583,
   problems: [
     {
       code: "ACCESS_DENIED",
@@ -15873,6 +15873,38 @@ export const CROCO_PROBLEM_CODE_REGISTRY = {
         },
       ],
     },
+    {
+      code: "transports-graphql/body-limit-invalid-configuration",
+      category: "InternalServerError",
+      status: 500,
+      title: "Internal Server Error",
+      cookbookPath:
+        "/reference/problem-recovery-cookbook/#transports-graphql-body-limit-invalid-configuration",
+      recovery: {
+        cause: "The GraphQL server was configured with an invalid request body byte boundary.",
+        userAction: "Ask the operator to correct the service configuration before retrying.",
+        operatorAction:
+          "Set maxBodySizeBytes to a finite positive safe integer and restart the service.",
+        retryability: "not-retryable",
+        redactionPolicy: "operator-only",
+        telemetry: {
+          eventName: "croco.problem.error",
+          severity: "error",
+          attributes: ["problem.code", "problem.category", "problem.status"],
+        },
+      },
+      lifecycle: {
+        status: "active",
+      },
+      sources: [
+        {
+          file: "packages/transports-graphql/src/libs/problems/GraphQLTransportProblems.ts",
+          line: 8,
+          column: 5,
+          kind: "problem-constructor",
+        },
+      ],
+    },
     {
       code: "transports-graphql/request-body-aborted",
       category: "BadRequest",
@@ -15898,7 +15930,7 @@ export const CROCO_PROBLEM_CODE_REGISTRY = {
       sources: [
         {
           file: "packages/transports-graphql/src/libs/problems/GraphQLTransportProblems.ts",
-          line: 47,
+          line: 63,
           column: 3,
           kind: "problem-class",
         },
@@ -15930,7 +15962,7 @@ export const CROCO_PROBLEM_CODE_REGISTRY = {
       sources: [
         {
           file: "packages/transports-graphql/src/libs/problems/GraphQLTransportProblems.ts",
-          line: 33,
+          line: 49,
           column: 5,
           kind: "problem-constructor",
         },
@@ -15963,7 +15995,7 @@ export const CROCO_PROBLEM_CODE_REGISTRY = {
       sources: [
         {
           file: "packages/transports-graphql/src/libs/problems/GraphQLTransportProblems.ts",
-          line: 4,
+          line: 20,
           column: 3,
           kind: "problem-class",
         },
@@ -15996,7 +16028,7 @@ export const CROCO_PROBLEM_CODE_REGISTRY = {
       sources: [
         {
           file: "packages/transports-graphql/src/libs/problems/GraphQLTransportProblems.ts",
-          line: 16,
+          line: 32,
           column: 3,
           kind: "problem-class",
         },
@@ -16029,7 +16061,7 @@ export const CROCO_PROBLEM_CODE_REGISTRY = {
       sources: [
         {
           file: "packages/transports-graphql/src/libs/problems/GraphQLTransportProblems.ts",
-          line: 24,
+          line: 40,
           column: 3,
           kind: "problem-class",
         },

diff --git a/packages/transports-graphql/README.md b/packages/transports-graphql/README.md
@@ -23,6 +23,12 @@ const schema = await new SchemaCompiler().compile({ resolvers: [HealthResolver]
 const server = new GraphQLServer({ schema });
 ```
 
+`maxBodySizeBytes` defaults to 1 MiB and must be a finite positive safe integer. The
+server validates this option during initialization, before opening its listener. Both
+declared `Content-Length` values and actual streamed bytes use an inclusive boundary:
+a request with exactly the configured number of bytes is accepted, while the next byte
+is rejected with `transports-graphql/request-body-too-large`.
+
 Schemas compiled through `SchemaCompiler` execute the `UseGuards`, `Roles`, and
 `UseInterceptors` declarations recorded by `@croco/protocols-graphql`. Request
 headers are available as `context.headers`, custom server context is preserved, and

diff --git a/packages/transports-graphql/src/index.ts b/packages/transports-graphql/src/index.ts
@@ -6,6 +6,7 @@
 /** GraphQL Yoga server runtime. */
 export { GraphQLServer } from "./libs/GraphQLServer";
 export {
+  GraphQLBodyLimitConfigurationProblem,
   GraphQLRequestBodyAbortedProblem,
   GraphQLRequestBodyTooLargeProblem,
   GraphQLResolversNotConfiguredProblem,

diff --git a/packages/transports-graphql/src/libs/GraphQLServer.ts b/packages/transports-graphql/src/libs/GraphQLServer.ts
@@ -6,6 +6,7 @@ import { Problem } from "@croco/problems-core";
 import { isProblem, problemToGraphQLError } from "@croco/protocols-graphql";
 import { createYoga, maskError } from "graphql-yoga";
 import {
+  GraphQLBodyLimitConfigurationProblem,
   GraphQLRequestBodyAbortedProblem,
   GraphQLRequestBodyTooLargeProblem,
   GraphQLSchemaNotConfiguredProblem,
@@ -38,12 +39,22 @@ export class GraphQLServer {
   private yogaHandler: YogaHandler | null = null;
   private server: Server | null = null;
   private initialized = false;
+  private maxBodySizeBytes = DEFAULT_MAX_BODY_SIZE_BYTES;
 
   constructor(private options: GraphQLServerOptions = {}) {}
 
   async initialize(): Promise<void> {
     if (this.initialized) return;
 
+    const maxBodySizeBytes =
+      this.options.maxBodySizeBytes === undefined
+        ? DEFAULT_MAX_BODY_SIZE_BYTES
+        : this.options.maxBodySizeBytes;
+    if (!Number.isSafeInteger(maxBodySizeBytes) || maxBodySizeBytes <= 0) {
+      throw new GraphQLBodyLimitConfigurationProblem();
+    }
+    this.maxBodySizeBytes = maxBodySizeBytes;
+
     const {
       schema,
       schemaOptions,
@@ -181,7 +192,7 @@ export class GraphQLServer {
 
   private getBody(req: IncomingMessage): Promise<string> {
     return new Promise((resolve, reject) => {
-      const maxBodySizeBytes = this.options.maxBodySizeBytes ?? DEFAULT_MAX_BODY_SIZE_BYTES;
+      const maxBodySizeBytes = this.maxBodySizeBytes;
       const contentLength = req.headers["content-length"];
 
       if (typeof contentLength === "string") {

diff --git a/packages/transports-graphql/src/libs/problems/GraphQLTransportProblems.ts b/packages/transports-graphql/src/libs/problems/GraphQLTransportProblems.ts
@@ -1,5 +1,21 @@
 import { Problem, ProblemCategory } from "@croco/problems-core";
 
+const PROBLEM_TYPE_BASE = "https://croco.dev/problems/transports-graphql";
+
+/** The configured request body boundary cannot be enforced safely. */
+export class GraphQLBodyLimitConfigurationProblem extends Problem {
+  constructor() {
+    super(
+      "transports-graphql/body-limit-invalid-configuration",
+      ProblemCategory.InternalServerError,
+      "maxBodySizeBytes must be a finite positive safe integer",
+      {
+        type: `${PROBLEM_TYPE_BASE}/body-limit-invalid-configuration`,
+      },
+    );
+  }
+}
+
 export class GraphQLResolversNotConfiguredProblem extends Problem {
   readonly code = "transports-graphql/resolvers-not-configured";
   readonly category = ProblemCategory.InternalServerError;