From f6428d02fcabc2e628f39b0e402f1a6eb0602649 Mon Sep 17 00:00:00 2001
From: Oluwatobi Mustapha <oluwatobimustapha539@gmail.com>
Date: Thu, 9 Apr 2026 21:44:35 +0100
Subject: [PATCH] fix(open-api): correct get-session nullable schema for OAS
 3.1 (#8389)

Co-authored-by: Maxwell <145994855+ping-maxwell@users.noreply.github.com>
Co-authored-by: ping-maxwell <maxwell.multinite@gmail.com>
---
 .changeset/honest-regions-jam.md                   |  5 +++++
 packages/better-auth/src/api/routes/session.ts     |  4 ++--
 .../open-api/__snapshots__/open-api.test.ts.snap   | 12 ++++++++----
 .../src/plugins/open-api/open-api.test.ts          | 14 ++++++++++++++
 4 files changed, 29 insertions(+), 6 deletions(-)
 create mode 100644 .changeset/honest-regions-jam.md

diff --git a/.changeset/honest-regions-jam.md b/.changeset/honest-regions-jam.md
new file mode 100644
index 0000000000..d0e0f03b28
--- /dev/null
+++ b/.changeset/honest-regions-jam.md
@@ -0,0 +1,5 @@
+---
+"better-auth": patch
+---
+
+fix(open-api): correct get-session nullable schema for OAS 3.1
diff --git a/packages/better-auth/src/api/routes/session.ts b/packages/better-auth/src/api/routes/session.ts
index c562776fc2..66c3c0611d 100644
--- a/packages/better-auth/src/api/routes/session.ts
+++ b/packages/better-auth/src/api/routes/session.ts
@@ -46,8 +46,8 @@ export const getSession = <Option extends BetterAuthOptions>() =>
 							content: {
 								"application/json": {
 									schema: {
-										type: "object",
-										nullable: true,
+										// better-call's OpenAPI schema type doesn't yet model OAS 3.1 union `type`.
+										type: ["object", "null"] as unknown as "object",
 										properties: {
 											session: {
 												$ref: "#/components/schemas/Session",
diff --git a/packages/better-auth/src/plugins/open-api/__snapshots__/open-api.test.ts.snap b/packages/better-auth/src/plugins/open-api/__snapshots__/open-api.test.ts.snap
index c10e83b6b7..eaf1bd1cc7 100644
--- a/packages/better-auth/src/plugins/open-api/__snapshots__/open-api.test.ts.snap
+++ b/packages/better-auth/src/plugins/open-api/__snapshots__/open-api.test.ts.snap
@@ -1591,7 +1591,6 @@ exports[`open-api > should generate OpenAPI schema > openAPISchema 1`] = `
             "content": {
               "application/json": {
                 "schema": {
-                  "nullable": true,
                   "properties": {
                     "session": {
                       "$ref": "#/components/schemas/Session",
@@ -1604,7 +1603,10 @@ exports[`open-api > should generate OpenAPI schema > openAPISchema 1`] = `
                     "session",
                     "user",
                   ],
-                  "type": "object",
+                  "type": [
+                    "object",
+                    "null",
+                  ],
                 },
               },
             },
@@ -1735,7 +1737,6 @@ exports[`open-api > should generate OpenAPI schema > openAPISchema 1`] = `
             "content": {
               "application/json": {
                 "schema": {
-                  "nullable": true,
                   "properties": {
                     "session": {
                       "$ref": "#/components/schemas/Session",
@@ -1748,7 +1749,10 @@ exports[`open-api > should generate OpenAPI schema > openAPISchema 1`] = `
                     "session",
                     "user",
                   ],
-                  "type": "object",
+                  "type": [
+                    "object",
+                    "null",
+                  ],
                 },
               },
             },
diff --git a/packages/better-auth/src/plugins/open-api/open-api.test.ts b/packages/better-auth/src/plugins/open-api/open-api.test.ts
index 6c14e56d8a..08e0adc398 100644
--- a/packages/better-auth/src/plugins/open-api/open-api.test.ts
+++ b/packages/better-auth/src/plugins/open-api/open-api.test.ts
@@ -125,6 +125,20 @@ describe("open-api", async () => {
 		);
 	});
 
+	it("should use OpenAPI 3.1 nullable format for get-session response", async () => {
+		const schema = await auth.api.generateOpenAPISchema();
+		const paths = schema.paths as Record<string, any>;
+
+		const getSessionSchema =
+			paths["/get-session"].post.responses["200"].content["application/json"]
+				.schema;
+
+		expect(Array.isArray(getSessionSchema.type)).toBe(true);
+		expect(getSessionSchema.type).toContain("object");
+		expect(getSessionSchema.type).toContain("null");
+		expect(getSessionSchema.nullable).toBe(undefined);
+	});
+
 	it("should use anyOf format for optional object types in OpenAPI 3.1", async () => {
 		const schema = await auth.api.generateOpenAPISchema();
 		const paths = schema.paths as Record<string, any>;