github-starred/better-auth
2
0
Fork 0
mirror of https://github.com/better-auth/better-auth.git synced 2026-05-24 16:11:53 -05:00
Code Issues 2.5k Packages Projects Releases 112 Wiki Activity

[GH-ISSUE #8688] Bug: auth.api.generateOpenAPISchema missing from Better Auth API typings #11161

New Issue
Open
opened 2026-04-13 07:31:20 -05:00 by GiteaMirror · 3 comments
GiteaMirror commented 2026-04-13 07:31:20 -05:00
Owner
Copy Link

Originally created by @Wadiou on GitHub (Mar 19, 2026).
Original GitHub issue: https://github.com/better-auth/better-auth/issues/8688

Is this suited for github?

  • Yes, this is suited for github

To Reproduce

A step-by-step description of how to reproduce the issue. If using code blocks, ensure syntax highlighting is correct.

  1. Install better-auth@1.5.5 and add the openAPI plugin to your auth config:
import { betterAuth } from 'better-auth';
import { openAPI } from 'better-auth/plugins';

export const auth = betterAuth({
  // ...database, session, etc.
  plugins: [openAPI()],
});
  1. Call the documented API to get the OpenAPI schema (e.g. for use with Scalar or unified docs):
async function getAuthOpenAPISchema() {
  const schema = await auth.api.generateOpenAPISchema();
  return schema;
}
  1. Run the TypeScript compiler or your IDE. TypeScript reports that generateOpenAPISchema does not exist on auth.api, even though the call works at runtime.

Current vs. Expected behavior

Following the steps from the previous section:

  • Expected: auth.api.generateOpenAPISchema() is present on the api object in the TypeScript types,and does not require any or type assertions to compile. Strict TypeScript / ESLint setups do not flag the call.

  • Actual: At runtime the method exists and works. In TypeScript, the inferred type of auth.api (the InferAPI<...> type) does not include generateOpenAPISchema, so you get errors such as:

    Property 'generateOpenAPISchema' does not exist on type 'InferAPI<...>'.

    To compile, you have to cast (e.g. (auth.api as any).generateOpenAPISchema()), which loses type safety and triggers no-unsafe-* ESLint rules unless disabled.

What version of Better Auth are you using?

1.5.5

System info

{
  "node": "v24.14.0",
  "better-auth": "1.5.5",
  "@better-auth/drizzle-adapter": "1.5.5",
  "@better-auth/cli": "1.4.21",
  "@thallesp/nestjs-better-auth": "2.5.1",
  "nestjs": "11.1.16",
  "typescript": "5.9.3",
  "typescript-eslint": "8.56.1"
}

Which area(s) are affected? (Select all that apply)

Types

Auth config (if applicable)

Additional context

No response

Originally created by @Wadiou on GitHub (Mar 19, 2026). Original GitHub issue: https://github.com/better-auth/better-auth/issues/8688 ### Is this suited for github? - [x] Yes, this is suited for github ### To Reproduce A step-by-step description of how to reproduce the issue. If using code blocks, ensure syntax highlighting is correct. 1. Install `better-auth@1.5.5` and add the `openAPI` plugin to your auth config: ```ts import { betterAuth } from 'better-auth'; import { openAPI } from 'better-auth/plugins'; export const auth = betterAuth({ // ...database, session, etc. plugins: [openAPI()], }); ``` 2. Call the documented API to get the OpenAPI schema (e.g. for use with Scalar or unified docs): ```ts async function getAuthOpenAPISchema() { const schema = await auth.api.generateOpenAPISchema(); return schema; } ``` 3. Run the TypeScript compiler or your IDE. TypeScript reports that `generateOpenAPISchema` does not exist on `auth.api`, even though the call works at runtime. ### Current vs. Expected behavior Following the steps from the previous section: - **Expected:** `auth.api.generateOpenAPISchema()` is present on the `api` object in the TypeScript types,and does not require `any` or type assertions to compile. Strict TypeScript / ESLint setups do not flag the call. - **Actual:** At runtime the method exists and works. In TypeScript, the inferred type of `auth.api` (the `InferAPI<...>` type) does **not** include `generateOpenAPISchema`, so you get errors such as: `Property 'generateOpenAPISchema' does not exist on type 'InferAPI<...>'.` To compile, you have to cast (e.g. `(auth.api as any).generateOpenAPISchema()`), which loses type safety and triggers `no-unsafe-*` ESLint rules unless disabled. ### What version of Better Auth are you using? 1.5.5 ### System info ```bash { "node": "v24.14.0", "better-auth": "1.5.5", "@better-auth/drizzle-adapter": "1.5.5", "@better-auth/cli": "1.4.21", "@thallesp/nestjs-better-auth": "2.5.1", "nestjs": "11.1.16", "typescript": "5.9.3", "typescript-eslint": "8.56.1" } ``` ### Which area(s) are affected? (Select all that apply) Types ### Auth config (if applicable) ```typescript ``` ### Additional context _No response_
GiteaMirror added the devtoolscorebug labels 2026-04-13 07:31:21 -05:00
GiteaMirror commented 2026-04-13 07:31:21 -05:00
Author
Owner
Copy Link

@dosubot[bot] commented on GitHub (Mar 19, 2026):

Hi @Wadiou! I'm Dosu and I’m helping the better-auth team.

This is a known TypeScript type inference limitation in better-auth. The generateOpenAPISchema endpoint is correctly defined in the openAPI plugin without any metadata flags that would exclude it from InferAPI, so it should appear in types.

The root cause is typically that plugins are defined outside the betterAuth() config. When this happens, TypeScript's type inference breaks down due to the complexity of better-auth's nested type transformations. This was explicitly reported: "if you move the openAPI plugin outside of the auth config the type inference for auth.api.generateOpenAPISchema is not there anymore."

Quick fix: Ensure all plugins are defined directly inside betterAuth():

export const auth = betterAuth({
  // ... other config
  plugins: [openAPI()], // ← Define directly here, not as a separate variable
});

If you must define plugins externally (e.g., to avoid "inferred type exceeds maximum length" errors), use as const:

const plugins = [openAPI()] as const;
export const auth = betterAuth({ plugins });

This issue is related to broader plugin type inference problems that have persisted across recent versions.

To reply, just mention @dosu.

How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other

Chat with Dosu Open in Cursor Join Discord Share on X

<!-- gh-comment-id:4090620882 --> @dosubot[bot] commented on GitHub (Mar 19, 2026): <!-- Greeting --> Hi @Wadiou! I'm [Dosu](https://go.dosu.dev/dosubot) and I’m helping the better-auth team. <!-- Answer --> This is a known TypeScript type inference limitation in better-auth. The `generateOpenAPISchema` endpoint is [correctly defined in the openAPI plugin](https://github.com/better-auth/better-auth/blob/a0211a05a6b21cbec8b2639cc063f0d04dc3a690/packages/better-auth/src/plugins/open-api/index.ts#L106-L115) without any metadata flags that would exclude it from `InferAPI`, so it should appear in types. The root cause is typically that **plugins are defined outside the `betterAuth()` config**. When this happens, TypeScript's type inference breaks down due to the complexity of better-auth's nested type transformations. This was [explicitly reported](https://github.com/better-auth/better-auth/issues/3408#issuecomment-3315955638): *"if you move the openAPI plugin outside of the auth config the type inference for `auth.api.generateOpenAPISchema` is not there anymore."* **Quick fix:** Ensure all plugins are defined directly inside `betterAuth()`: ```typescript export const auth = betterAuth({ // ... other config plugins: [openAPI()], // ← Define directly here, not as a separate variable }); ``` If you must define plugins externally (e.g., to avoid "inferred type exceeds maximum length" errors), use `as const`: ```typescript const plugins = [openAPI()] as const; export const auth = betterAuth({ plugins }); ``` This issue is related to [broader plugin type inference problems](https://github.com/better-auth/better-auth/issues/7219) that have persisted across recent versions. <!-- Dosu Comment Footer --> *To reply, just mention [@dosu](https://go.dosu.dev/dosubot?utm_source=github&utm_medium=bot-comment&utm_campaign=github-assistant&utm_content=brand-link).* --- <sup>How did I do? [Good](https://app.dosu.dev/response-feedback/48b26411-6201-4799-913a-a3ba3dadf46c?feedback_type=great_response&utm_source=github&utm_medium=bot-comment&utm_campaign=github-assistant&utm_content=feedback-great_response) | [Irrelevant](https://app.dosu.dev/response-feedback/48b26411-6201-4799-913a-a3ba3dadf46c?feedback_type=irrelevant_answer&utm_source=github&utm_medium=bot-comment&utm_campaign=github-assistant&utm_content=feedback-irrelevant_answer) | [Incorrect](https://app.dosu.dev/response-feedback/48b26411-6201-4799-913a-a3ba3dadf46c?feedback_type=incorrect_sources&utm_source=github&utm_medium=bot-comment&utm_campaign=github-assistant&utm_content=feedback-incorrect_sources) | [Verbose](https://app.dosu.dev/response-feedback/48b26411-6201-4799-913a-a3ba3dadf46c?feedback_type=too_verbose&utm_source=github&utm_medium=bot-comment&utm_campaign=github-assistant&utm_content=feedback-too_verbose) | [Hallucination](https://app.dosu.dev/response-feedback/48b26411-6201-4799-913a-a3ba3dadf46c?feedback_type=hallucination&utm_source=github&utm_medium=bot-comment&utm_campaign=github-assistant&utm_content=feedback-hallucination) | [Report 🐛](https://app.dosu.dev/response-feedback/48b26411-6201-4799-913a-a3ba3dadf46c?feedback_type=bug_report&utm_source=github&utm_medium=bot-comment&utm_campaign=github-assistant&utm_content=feedback-bug_report) | [Other](https://app.dosu.dev/response-feedback/48b26411-6201-4799-913a-a3ba3dadf46c?feedback_type=other&utm_source=github&utm_medium=bot-comment&utm_campaign=github-assistant&utm_content=feedback-other)</sup> [![Chat with Dosu](https://dosu.dev/dosu-chat-badge.svg)](https://app.dosu.dev/cdda13d9-dd27-4d31-b09a-5d8bec92de21/ask?utm_source=github&utm_medium=bot-comment&utm_campaign=github-assistant&utm_content=chat-badge)&nbsp;[![Open in Cursor](https://dosu.dev/dosu-in-cursor.svg)](https://cursor.com/link/prompt?text=This%20is%20a%20known%20TypeScript%20type%20inference%20limitation%20in%20better-auth.%20The%20%60generateOpenAPISchema%60%20endpoint%20is%20%5Bcorrectly%20defined%20in%20the%20openAPI%20plugin%5D%28https%3A//github.com/better-auth/better-auth/blob/a0211a05a6b21cbec8b2639cc063f0d04dc3a690/packages/better-auth/src/plugins/open-api/index.ts%23L106-L115%29%20without%20any%20metadata%20flags%20that%20would%20exclude%20it%20from%20%60InferAPI%60%2C%20so%20it%20should%20appear%20in%20types.%0A%0AThe%20root%20cause%20is%20typically%20that%20%2A%2Aplugins%20are%20defined%20outside%20the%20%60betterAuth%28%29%60%20config%2A%2A.%20When%20this%20happens%2C%20TypeScript%27s%20type%20inference%20breaks%20down%20due%20to%20the%20complexity%20of%20better-auth%27s%20nested%20type%20transformations.%20This%20was%20%5Bexplicitly%20reported%5D%28https%3A//github.com/better-auth/better-auth/issues/3408%23issuecomment-3315955638%29%3A%20%2A%22if%20you%20move%20the%20openAPI%20plugin%20outside%20of%20the%20auth%20config%20the%20type%20inference%20for%20%60auth.api.generateOpenAPISchema%60%20is%20not%20there%20anymore.%22%2A%0A%0A%2A%2AQuick%20fix%3A%2A%2A%20Ensure%20all%20plugins%20are%20defined%20directly%20inside%20%60betterAuth%28%29%60%3A%0A%0A%60%60%60typescript%0Aexport%20const%20auth%20%3D%20betterAuth%28%7B%0A%20%20//%20...%20other%20config%0A%20%20plugins%3A%20%5BopenAPI%28%29%5D%2C%20//%20%E2%86%90%20Define%20directly%20here%2C%20not%20as%20a%20separate%20variable%0A%7D%29%3B%0A%60%60%60%0A%0AIf%20you%20must%20define%20plugins%20externally%20%28e.g.%2C%20to%20avoid%20%22inferred%20type%20exceeds%20maximum%20length%22%20errors%29%2C%20use%20%60as%20const%60%3A%0A%0A%60%60%60typescript%0Aconst%20plugins%20%3D%20%5BopenAPI%28%29%5D%20as%20const%3B%0Aexport%20const%20auth%20%3D%20betterAuth%28%7B%20plugins%20%7D%29%3B%0A%60%60%60%0A%0AThis%20issue%20is%20related%20to%20%5Bbroader%20plugin%20type%20inference%20problems%5D%28https%3A//github.com/better-auth/better-auth/issues/7219%29%20that%20have%20persisted%20across%20recent%20versions.)&nbsp;[![Join Discord](https://img.shields.io/badge/join-5865F2?logo=discord&logoColor=white&label=)](https://go.dosu.dev/discord-bot?utm_source=github&utm_medium=bot-comment&utm_campaign=github-assistant&utm_content=join-discord)&nbsp;[![Share on X](https://img.shields.io/badge/X-share-black)](https://twitter.com/intent/tweet?text=%40dosu_ai%20helped%20me%20solve%20this%20issue!&url=https%3A//github.com/better-auth/better-auth/issues/8688)
GiteaMirror commented 2026-04-13 07:31:22 -05:00
Author
Owner
Copy Link

@NathanVeeva commented on GitHub (Mar 20, 2026):

@dosu As you mentioned this is an on going bug, like @Wadiou this is still an issue with the sso() plugin. Adding it directly or defining it outside still causes type infer issues where the auth instance api is typed any https://github.com/better-auth/better-auth/issues/7219#issuecomment-4082083635

<!-- gh-comment-id:4097849935 --> @NathanVeeva commented on GitHub (Mar 20, 2026): @dosu As you mentioned this is an on going bug, like @Wadiou this is still an issue with the `sso()` plugin. Adding it directly or defining it outside still causes type infer issues where the auth instance `api` is typed `any` https://github.com/better-auth/better-auth/issues/7219#issuecomment-4082083635
GiteaMirror commented 2026-04-13 07:31:22 -05:00
Author
Owner
Copy Link

@alex-delia commented on GitHub (Mar 24, 2026):

This issue also exists on the most recent version 1.5.6 with the Polar plugin. Something like authClient.customer.portal() types correctly, but authClient.customer.benefits.list(); types as 'any'. This is has been an ongoing issue with plugins that isn't resolved

<!-- gh-comment-id:4116179949 --> @alex-delia commented on GitHub (Mar 24, 2026): This issue also exists on the most recent version 1.5.6 with the Polar plugin. Something like authClient.customer.portal() types correctly, but authClient.customer.benefits.list(); types as 'any'. This is has been an ongoing issue with plugins that isn't resolved
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
adapter
astro
awaiting external contributor
blocked
breaking
breaking change
bug
c-devops
core
credentials
database
dependencies
devops
devtools
docs
documentation
duplicate
elysia
enhancement
enterprise
expo
express
fastify
good first issue
help wanted
hono
identity
infra
integration
invalid
javascript
locked
maintenance
need-more-information
needs: info
needs: repro
nextjs
nuxt
oauth
organization
P0
payments
perf
platform
plugin
pull-request
Mirrored from GitHub Pull Request
 question
ready
regression
remix
security
social-provider
solid
stale
svelte
tanstack-start
tracking
version-bump
vue
wontfix
No Label bug core devtools
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
GiteaMirror ninjasurge
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: github-starred/better-auth#11161
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?