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

Regression due to changed types in admin plugin hooks #2235

New Issue
Closed
opened 2026-03-13 09:37:06 -05:00 by GiteaMirror · 21 comments
GiteaMirror commented 2026-03-13 09:37:06 -05:00
Owner
Copy Link

Originally created by @ChristianIvicevic on GitHub (Oct 30, 2025).

Is this suited for github?

  • Yes, this is suited for github

To Reproduce

Reproduction repository: https://github.com/ChristianIvicevic/better-auth-headers-repro

Open the src/index.ts file and notice how admin() cannot be passed to the plugins array without a type error due to possibly undefined headers in the hooks, which hasn't been the case before.

This is a regression since 1.3.28, the previous version 1.3.27 does NOT have the same issue.

Current vs. Expected behavior

Currently, throwing the following type error:

Type '{ id: "admin"; init(): { options: { databaseHooks: { user: { create: { before(user: { id: string; createdAt: Date; updatedAt: Date; email: string; emailVerified: boolean; name: string; image?: string | ... 1 more ... | undefined; } & Record<...>): Promise<...>; }; }; session: { ...; }; }; }; }; ... 4 more ...; optio...' is not assignable to type 'BetterAuthPlugin'.
  The types of 'hooks.after' are incompatible between these types.
    Type '{ matcher(context: EndpointContext<string, any> & Omit<InputContext<string, any>, "method"> & { context: AuthContext & { returned?: unknown; responseHeaders?: Headers; }; headers?: Headers; }): boolean; handler: (inputContext: MiddlewareInputContext<...>) => Promise<...>; }[]' is not assignable to type '{ matcher: (context: HookEndpointContext) => boolean; handler: (inputContext: MiddlewareInputContext<MiddlewareOptions>) => Promise<...>; }[]'.
      Type '{ matcher(context: EndpointContext<string, any> & Omit<InputContext<string, any>, "method"> & { context: AuthContext & { returned?: unknown; responseHeaders?: Headers; }; headers?: Headers; }): boolean; handler: (inputContext: MiddlewareInputContext<...>) => Promise<...>; }' is not assignable to type '{ matcher: (context: HookEndpointContext) => boolean; handler: (inputContext: MiddlewareInputContext<MiddlewareOptions>) => Promise<...>; }'.
        Types of property 'matcher' are incompatible.
          Type '(context: EndpointContext<string, any> & Omit<InputContext<string, any>, "method"> & { context: AuthContext & { returned?: unknown; responseHeaders?: Headers; }; headers?: Headers; }) => boolean' is not assignable to type '(context: HookEndpointContext) => boolean'.
            Types of parameters 'context' and 'context' are incompatible.
              Type 'HookEndpointContext' is not assignable to type 'EndpointContext<string, any> & Omit<InputContext<string, any>, "method"> & { context: AuthContext & { returned?: unknown; responseHeaders?: Headers; }; headers?: Headers; }' with 'exactOptionalPropertyTypes: true'. Consider adding 'undefined' to the types of the target's properties.
                Type 'HookEndpointContext' is not assignable to type '{ context: AuthContext & { returned?: unknown; responseHeaders?: Headers; }; headers?: Headers; }' with 'exactOptionalPropertyTypes: true'. Consider adding 'undefined' to the types of the target's properties.
                  Types of property 'headers' are incompatible.
                    Type '(Headers & HeadersInit) | undefined' is not assignable to type 'Headers'.
                      Type 'undefined' is not assignable to type 'Headers'.ts(2322)

What version of Better Auth are you using?

1.3.28

System info

{
  "system": {
    "platform": "darwin",
    "arch": "arm64",
    "version": "Darwin Kernel Version 24.6.0: Mon Jul 14 11:30:55 PDT 2025; root:xnu-11417.140.69~1/RELEASE_ARM64_T6031",
    "release": "24.6.0",
    "cpuCount": 16,
    "cpuModel": "Apple M3 Max",
    "totalMemory": "48.00 GB",
    "freeMemory": "3.33 GB"
  },
  "node": {
    "version": "v22.20.0",
    "env": "development"
  },
  "packageManager": {
    "name": "npm",
    "version": "10.9.3"
  },
  "frameworks": null,
  "databases": null,
  "betterAuth": {
    "version": "1.3.28",
    "config": null
  }
}

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

Backend

Auth config (if applicable)

import { betterAuth } from 'better-auth'
import { admin } from 'better-auth/plugins'

const auth = betterAuth({ plugins: [admin()] })

Additional context

No response

Originally created by @ChristianIvicevic on GitHub (Oct 30, 2025). ### Is this suited for github? - [x] Yes, this is suited for github ### To Reproduce Reproduction repository: https://github.com/ChristianIvicevic/better-auth-headers-repro Open the `src/index.ts` file and notice how `admin()` cannot be passed to the `plugins` array without a type error due to possibly undefined headers in the hooks, which hasn't been the case before. This is a regression since 1.3.28, the previous version 1.3.27 does NOT have the same issue. ### Current vs. Expected behavior Currently, throwing the following type error: ``` Type '{ id: "admin"; init(): { options: { databaseHooks: { user: { create: { before(user: { id: string; createdAt: Date; updatedAt: Date; email: string; emailVerified: boolean; name: string; image?: string | ... 1 more ... | undefined; } & Record<...>): Promise<...>; }; }; session: { ...; }; }; }; }; ... 4 more ...; optio...' is not assignable to type 'BetterAuthPlugin'. The types of 'hooks.after' are incompatible between these types. Type '{ matcher(context: EndpointContext<string, any> & Omit<InputContext<string, any>, "method"> & { context: AuthContext & { returned?: unknown; responseHeaders?: Headers; }; headers?: Headers; }): boolean; handler: (inputContext: MiddlewareInputContext<...>) => Promise<...>; }[]' is not assignable to type '{ matcher: (context: HookEndpointContext) => boolean; handler: (inputContext: MiddlewareInputContext<MiddlewareOptions>) => Promise<...>; }[]'. Type '{ matcher(context: EndpointContext<string, any> & Omit<InputContext<string, any>, "method"> & { context: AuthContext & { returned?: unknown; responseHeaders?: Headers; }; headers?: Headers; }): boolean; handler: (inputContext: MiddlewareInputContext<...>) => Promise<...>; }' is not assignable to type '{ matcher: (context: HookEndpointContext) => boolean; handler: (inputContext: MiddlewareInputContext<MiddlewareOptions>) => Promise<...>; }'. Types of property 'matcher' are incompatible. Type '(context: EndpointContext<string, any> & Omit<InputContext<string, any>, "method"> & { context: AuthContext & { returned?: unknown; responseHeaders?: Headers; }; headers?: Headers; }) => boolean' is not assignable to type '(context: HookEndpointContext) => boolean'. Types of parameters 'context' and 'context' are incompatible. Type 'HookEndpointContext' is not assignable to type 'EndpointContext<string, any> & Omit<InputContext<string, any>, "method"> & { context: AuthContext & { returned?: unknown; responseHeaders?: Headers; }; headers?: Headers; }' with 'exactOptionalPropertyTypes: true'. Consider adding 'undefined' to the types of the target's properties. Type 'HookEndpointContext' is not assignable to type '{ context: AuthContext & { returned?: unknown; responseHeaders?: Headers; }; headers?: Headers; }' with 'exactOptionalPropertyTypes: true'. Consider adding 'undefined' to the types of the target's properties. Types of property 'headers' are incompatible. Type '(Headers & HeadersInit) | undefined' is not assignable to type 'Headers'. Type 'undefined' is not assignable to type 'Headers'.ts(2322) ``` ### What version of Better Auth are you using? 1.3.28 ### System info ```bash { "system": { "platform": "darwin", "arch": "arm64", "version": "Darwin Kernel Version 24.6.0: Mon Jul 14 11:30:55 PDT 2025; root:xnu-11417.140.69~1/RELEASE_ARM64_T6031", "release": "24.6.0", "cpuCount": 16, "cpuModel": "Apple M3 Max", "totalMemory": "48.00 GB", "freeMemory": "3.33 GB" }, "node": { "version": "v22.20.0", "env": "development" }, "packageManager": { "name": "npm", "version": "10.9.3" }, "frameworks": null, "databases": null, "betterAuth": { "version": "1.3.28", "config": null } } ``` ### Which area(s) are affected? (Select all that apply) Backend ### Auth config (if applicable) ```typescript import { betterAuth } from 'better-auth' import { admin } from 'better-auth/plugins' const auth = betterAuth({ plugins: [admin()] }) ``` ### Additional context _No response_
GiteaMirror added the bug label 2026-03-13 09:37:06 -05:00
GiteaMirror commented 2026-03-13 09:37:07 -05:00
Author
Owner
Copy Link

@better-auth-agent[bot] commented on GitHub (Oct 30, 2025):

It looks like the recent update in version 1.3.28 changed the expected types for admin hook contexts—specifically, the matcher function now requires a non‑nullable headers property (of type Headers), while in practice the hook’s context might have an undefined headers field. This is a regression compared to 1.3.27 where the types allowed for undefined headers, and it’s causing the type error you’re seeing.

As a next step, you have a couple of workarounds:

  1. Roll back to version 1.3.27 until a fix is released. This will restore the previous behavior with the compatible hook types.
  2. Alternatively, if you need to stay on 1.3.28, you can temporarily adjust your plugin’s hook types (or use a type assertion) so that the headers property is explicitly marked as possibly undefined. For example, you could cast the hook or modify the matcher signature locally to accept undefined headers. This should bypass the type error while you wait for an official fix.

Our team is aware of the issue and is working on a patch that will properly align the hook types, so please keep an eye on the release notes for an upcoming update.

These steps should help you troubleshoot the issue in the meantime [1].

Diagram • Discord • GitHub

Diagram Join Star

@better-auth-agent[bot] commented on GitHub (Oct 30, 2025): It looks like the recent update in version 1.3.28 changed the expected types for admin hook contexts—specifically, the matcher function now requires a non‑nullable headers property (of type Headers), while in practice the hook’s context might have an undefined headers field. This is a regression compared to 1.3.27 where the types allowed for undefined headers, and it’s causing the type error you’re seeing. As a next step, you have a couple of workarounds: 1. Roll back to version 1.3.27 until a fix is released. This will restore the previous behavior with the compatible hook types. 2. Alternatively, if you need to stay on 1.3.28, you can temporarily adjust your plugin’s hook types (or use a type assertion) so that the headers property is explicitly marked as possibly undefined. For example, you could cast the hook or modify the matcher signature locally to accept undefined headers. This should bypass the type error while you wait for an official fix. Our team is aware of the issue and is working on a patch that will properly align the hook types, so please keep an eye on the release notes for an upcoming update. These steps should help you troubleshoot the issue in the meantime [[1]](https://github.com/better-auth/better-auth/issues/1578). <!-- bot:webhook reply v1 --> [Diagram](https://repodiagrams.s3.eu-north-1.amazonaws.com/better-auth_ultra_detailed_interactive.html) • [Discord](https://discord.gg/better-auth) • [GitHub](https://github.com/better-auth/better-auth) [![Diagram](https://img.shields.io/badge/Diagram-2b3137?style=flat-square)](https://repodiagrams.s3.eu-north-1.amazonaws.com/better-auth_ultra_detailed_interactive.html) [![Join](https://img.shields.io/badge/join-5865F2?logo=discord&logoColor=white&style=flat-square)](https://discord.gg/better-auth) [![Star](https://img.shields.io/badge/star-181717?logo=github&logoColor=white&style=flat-square)](https://github.com/better-auth/better-auth)
GiteaMirror commented 2026-03-13 09:37:08 -05:00
Author
Owner
Copy Link

@ping-maxwell commented on GitHub (Oct 30, 2025):

can you share your tsconfig?

@ping-maxwell commented on GitHub (Oct 30, 2025): can you share your tsconfig?
GiteaMirror commented 2026-03-13 09:37:09 -05:00
Author
Owner
Copy Link

@better-auth-agent[bot] commented on GitHub (Oct 30, 2025):

Based on the error message and regression details, it seems that the new version enforces stricter checking for the headers property on your hooks. To troubleshoot, please verify your tsconfig settings—specifically, check whether the option "exactOptionalPropertyTypes" is enabled. The new definitions expect that headers cannot be undefined unless explicitly allowed. You can try one or more of the following steps:

  1. Temporarily disable "exactOptionalPropertyTypes" (or allow undefined explicitly) so that your admin plugin’s hook types align with what’s expected.
  2. If you need the strictness enabled for other parts of your project, consider patching the type definitions (for example, by augmenting the hook context types to allow undefined headers) until a proper fix is released.
  3. As a workaround, you might revert to version 1.3.27 for the time being if that meets your project’s requirements.

Please share your tsconfig file to help further pinpoint any conflicts [1].

Diagram • Discord • GitHub

Diagram Join Star

@better-auth-agent[bot] commented on GitHub (Oct 30, 2025): Based on the error message and regression details, it seems that the new version enforces stricter checking for the headers property on your hooks. To troubleshoot, please verify your tsconfig settings—specifically, check whether the option "exactOptionalPropertyTypes" is enabled. The new definitions expect that headers cannot be undefined unless explicitly allowed. You can try one or more of the following steps: 1. Temporarily disable "exactOptionalPropertyTypes" (or allow undefined explicitly) so that your admin plugin’s hook types align with what’s expected. 2. If you need the strictness enabled for other parts of your project, consider patching the type definitions (for example, by augmenting the hook context types to allow undefined headers) until a proper fix is released. 3. As a workaround, you might revert to version 1.3.27 for the time being if that meets your project’s requirements. Please share your tsconfig file to help further pinpoint any conflicts [[1]](https://github.com/better-auth/better-auth/issues/5674). <!-- bot:webhook reply v1 --> [Diagram](https://repodiagrams.s3.eu-north-1.amazonaws.com/better-auth_ultra_detailed_interactive.html) • [Discord](https://discord.gg/better-auth) • [GitHub](https://github.com/better-auth/better-auth) [![Diagram](https://img.shields.io/badge/Diagram-2b3137?style=flat-square)](https://repodiagrams.s3.eu-north-1.amazonaws.com/better-auth_ultra_detailed_interactive.html) [![Join](https://img.shields.io/badge/join-5865F2?logo=discord&logoColor=white&style=flat-square)](https://discord.gg/better-auth) [![Star](https://img.shields.io/badge/star-181717?logo=github&logoColor=white&style=flat-square)](https://github.com/better-auth/better-auth)
GiteaMirror commented 2026-03-13 09:37:10 -05:00
Author
Owner
Copy Link

@ping-maxwell commented on GitHub (Oct 30, 2025):

oh, got it:

{
	"compilerOptions": {
		"disableSourceOfProjectReferenceRedirect": true,
        "allowJs": false,
		"checkJs": false,
		"composite": true,
		"declaration": true,
		"declarationMap": true,
		"downlevelIteration": true,
		"emitDecoratorMetadata": true,
		"esModuleInterop": false,
		"exactOptionalPropertyTypes": true,
		"experimentalDecorators": true,
		"forceConsistentCasingInFileNames": true,
		"module": "Preserve",
		"moduleDetection": "force",
		"moduleResolution": "bundler",
		"noEmitOnError": false,
		"noErrorTruncation": false,
		"noFallthroughCasesInSwitch": true,
		"noImplicitAny": true,
		"noImplicitReturns": false,
		"noImplicitThis": true,
		"noUncheckedIndexedAccess": true,
		"noUnusedLocals": true,
		"noUnusedParameters": false,
		"removeComments": false,
		"sourceMap": true,
		"strictNullChecks": true,
		"target": "ES2023",
		"baseUrl": "./src",
		"incremental": true,
		"isolatedModules": true,
		"lib": ["ES2022", "ES2023", "DOM", "DOM.Iterable"],
		"noEmit": true,
		"outDir": "dist",
		"resolveJsonModule": true,
		"rootDir": ".",
		"skipLibCheck": true,
		"strict": true,
		"tsBuildInfoFile": ".tsbuildinfo/src.tsbuildinfo"
	},
	"exclude": ["node_modules"],
	"include": ["src", "test"]
}
@ping-maxwell commented on GitHub (Oct 30, 2025): oh, got it: ```json { "compilerOptions": { "disableSourceOfProjectReferenceRedirect": true, "allowJs": false, "checkJs": false, "composite": true, "declaration": true, "declarationMap": true, "downlevelIteration": true, "emitDecoratorMetadata": true, "esModuleInterop": false, "exactOptionalPropertyTypes": true, "experimentalDecorators": true, "forceConsistentCasingInFileNames": true, "module": "Preserve", "moduleDetection": "force", "moduleResolution": "bundler", "noEmitOnError": false, "noErrorTruncation": false, "noFallthroughCasesInSwitch": true, "noImplicitAny": true, "noImplicitReturns": false, "noImplicitThis": true, "noUncheckedIndexedAccess": true, "noUnusedLocals": true, "noUnusedParameters": false, "removeComments": false, "sourceMap": true, "strictNullChecks": true, "target": "ES2023", "baseUrl": "./src", "incremental": true, "isolatedModules": true, "lib": ["ES2022", "ES2023", "DOM", "DOM.Iterable"], "noEmit": true, "outDir": "dist", "resolveJsonModule": true, "rootDir": ".", "skipLibCheck": true, "strict": true, "tsBuildInfoFile": ".tsbuildinfo/src.tsbuildinfo" }, "exclude": ["node_modules"], "include": ["src", "test"] } ```
GiteaMirror commented 2026-03-13 09:37:11 -05:00
Author
Owner
Copy Link

@better-auth-agent[bot] commented on GitHub (Oct 30, 2025):

It appears that the new type error is caused by stricter enforcement of the exact optional property types (specifically the headers property potentially being undefined) in version 1.3.28. This regression did not occur in 1.3.27 because the hook types did not account for the possibility of an undefined header.

Next steps to troubleshoot:

  1. As a temporary workaround, you could try disabling the exactOptionalPropertyTypes flag in your tsconfig to see if the issue goes away. This isn’t ideal long term, but it will confirm that the stricter type checking is causing the error.
  2. Alternatively, you can adjust your custom type definitions (or use module augmentation) to explicitly allow headers to be undefined in hook contexts. In particular, update the target type for headers so that it accepts Headers | undefined.
  3. If neither change is acceptable for your project, consider reverting to version 1.3.27 until a fix is released.
  4. Finally, you may want to file an issue (or add details to the existing one) with the Better Auth team to let them know that the changes in the hook types (and their compatibility with exactOptionalPropertyTypes) are causing regression problems.

These steps should help you isolate the problem and decide on the best course until an official patch is available [1].

Diagram • Discord • GitHub

Diagram Join Star

@better-auth-agent[bot] commented on GitHub (Oct 30, 2025): It appears that the new type error is caused by stricter enforcement of the exact optional property types (specifically the headers property potentially being undefined) in version 1.3.28. This regression did not occur in 1.3.27 because the hook types did not account for the possibility of an undefined header. Next steps to troubleshoot: 1. As a temporary workaround, you could try disabling the exactOptionalPropertyTypes flag in your tsconfig to see if the issue goes away. This isn’t ideal long term, but it will confirm that the stricter type checking is causing the error. 2. Alternatively, you can adjust your custom type definitions (or use module augmentation) to explicitly allow headers to be undefined in hook contexts. In particular, update the target type for headers so that it accepts Headers | undefined. 3. If neither change is acceptable for your project, consider reverting to version 1.3.27 until a fix is released. 4. Finally, you may want to file an issue (or add details to the existing one) with the Better Auth team to let them know that the changes in the hook types (and their compatibility with exactOptionalPropertyTypes) are causing regression problems. These steps should help you isolate the problem and decide on the best course until an official patch is available [[1]](https://github.com/better-auth/better-auth/issues/5674). <!-- bot:webhook reply v1 --> [Diagram](https://repodiagrams.s3.eu-north-1.amazonaws.com/better-auth_ultra_detailed_interactive.html) • [Discord](https://discord.gg/better-auth) • [GitHub](https://github.com/better-auth/better-auth) [![Diagram](https://img.shields.io/badge/Diagram-2b3137?style=flat-square)](https://repodiagrams.s3.eu-north-1.amazonaws.com/better-auth_ultra_detailed_interactive.html) [![Join](https://img.shields.io/badge/join-5865F2?logo=discord&logoColor=white&style=flat-square)](https://discord.gg/better-auth) [![Star](https://img.shields.io/badge/star-181717?logo=github&logoColor=white&style=flat-square)](https://github.com/better-auth/better-auth)
GiteaMirror commented 2026-03-13 09:37:11 -05:00
Author
Owner
Copy Link

@ping-maxwell commented on GitHub (Oct 30, 2025):

Better-auth tends to break when declaration, declarationMap, exactOptionalPropertyTypes are enabled.
Although I believe some of our team members have worked on improving this if not resolves these already..

cc @himself65

@ping-maxwell commented on GitHub (Oct 30, 2025): Better-auth tends to break when `declaration`, `declarationMap`, `exactOptionalPropertyTypes` are enabled. Although I believe some of our team members have worked on improving this if not resolves these already.. cc @himself65
GiteaMirror commented 2026-03-13 09:37:12 -05:00
Author
Owner
Copy Link

@better-auth-agent[bot] commented on GitHub (Oct 30, 2025):

It looks like a regression was introduced in 1.3.28 where the admin plugin’s hook types now require that header properties be explicitly defined (or at least defaulted), which wasn’t enforced in the previous version. Here are some next steps:

  1. As a temporary workaround, you can either pin your Better Auth dependency to 1.3.27 or explicitly cast/extend your headers in your TS configuration so they’re no longer possibly undefined. This might involve providing a default Headers value when processing hooks.

  2. Double-check your tsconfig settings (especially options like declaration, declarationMap, and exactOptionalPropertyTypes) since stricter type checks seem to trigger this error. Adjusting these might help in the short term.

  3. Finally, raise or comment on the existing GitHub issue (cc’ing the maintainers) to verify whether a patch or beta release is available that resolves the regression. Some team members have reportedly been working on improvements in this area, so a fix might be on the way [1][2].

By following these steps, you should be able to either work around the issue or help expedite a proper fix.

Diagram • Discord • GitHub

Diagram Join Star

@better-auth-agent[bot] commented on GitHub (Oct 30, 2025): It looks like a regression was introduced in 1.3.28 where the admin plugin’s hook types now require that header properties be explicitly defined (or at least defaulted), which wasn’t enforced in the previous version. Here are some next steps: 1. As a temporary workaround, you can either pin your Better Auth dependency to 1.3.27 or explicitly cast/extend your headers in your TS configuration so they’re no longer possibly undefined. This might involve providing a default Headers value when processing hooks. 2. Double-check your tsconfig settings (especially options like declaration, declarationMap, and exactOptionalPropertyTypes) since stricter type checks seem to trigger this error. Adjusting these might help in the short term. 3. Finally, raise or comment on the existing GitHub issue (cc’ing the maintainers) to verify whether a patch or beta release is available that resolves the regression. Some team members have reportedly been working on improvements in this area, so a fix might be on the way [[1]](https://github.com/better-auth/better-auth/issues/5674)[[2]](https://github.com/better-auth/better-auth/issues/1578). By following these steps, you should be able to either work around the issue or help expedite a proper fix. <!-- bot:webhook reply v1 --> [Diagram](https://repodiagrams.s3.eu-north-1.amazonaws.com/better-auth_ultra_detailed_interactive.html) • [Discord](https://discord.gg/better-auth) • [GitHub](https://github.com/better-auth/better-auth) [![Diagram](https://img.shields.io/badge/Diagram-2b3137?style=flat-square)](https://repodiagrams.s3.eu-north-1.amazonaws.com/better-auth_ultra_detailed_interactive.html) [![Join](https://img.shields.io/badge/join-5865F2?logo=discord&logoColor=white&style=flat-square)](https://discord.gg/better-auth) [![Star](https://img.shields.io/badge/star-181717?logo=github&logoColor=white&style=flat-square)](https://github.com/better-auth/better-auth)
GiteaMirror commented 2026-03-13 09:37:12 -05:00
Author
Owner
Copy Link

@ChristianIvicevic commented on GitHub (Oct 30, 2025):

I can confirm that exactOptionalPropertyTypes is the cause of the regression, but you can imagine that reducing strictness is not a maintainable long-term solution.

@ChristianIvicevic commented on GitHub (Oct 30, 2025): I can confirm that `exactOptionalPropertyTypes` is the cause of the regression, but you can imagine that reducing strictness is not a maintainable long-term solution.
GiteaMirror commented 2026-03-13 09:37:13 -05:00
Author
Owner
Copy Link

@better-auth-agent[bot] commented on GitHub (Oct 30, 2025):

Based on your report, the issue is caused by the stricter checking that comes with exactOptionalPropertyTypes—now the hook context’s headers property may be undefined, which wasn’t allowed by the plugin’s type. The next steps are:

  1. Update the type definitions for your plugin’s hooks so that they explicitly allow headers to be undefined (for example, by marking it as Headers | undefined). This change aligns with the exactOptionalPropertyTypes behavior without reducing TypeScript strictness [1].

  2. As a short‑term workaround, you might consider providing a default headers object in your hook implementations (or using a type cast) so that the type error is bypassed. However, this is not ideal for long‑term maintainability.

  3. Keep an eye on the upcoming releases or patches for Better Auth, where the admin plugin types may be updated to handle this case in a more robust way [1].

These steps should help you move forward without compromising on the strictness that exactOptionalPropertyTypes enforces. If you need further assistance with modifying the types, let us know.

Diagram • Discord • GitHub

Diagram Join Star

@better-auth-agent[bot] commented on GitHub (Oct 30, 2025): Based on your report, the issue is caused by the stricter checking that comes with exactOptionalPropertyTypes—now the hook context’s headers property may be undefined, which wasn’t allowed by the plugin’s type. The next steps are: 1. Update the type definitions for your plugin’s hooks so that they explicitly allow headers to be undefined (for example, by marking it as Headers | undefined). This change aligns with the exactOptionalPropertyTypes behavior without reducing TypeScript strictness [[1]](https://github.com/better-auth/better-auth/issues/5674). 2. As a short‑term workaround, you might consider providing a default headers object in your hook implementations (or using a type cast) so that the type error is bypassed. However, this is not ideal for long‑term maintainability. 3. Keep an eye on the upcoming releases or patches for Better Auth, where the admin plugin types may be updated to handle this case in a more robust way [[1]](https://github.com/better-auth/better-auth/issues/5674). These steps should help you move forward without compromising on the strictness that exactOptionalPropertyTypes enforces. If you need further assistance with modifying the types, let us know. <!-- bot:webhook reply v1 --> [Diagram](https://repodiagrams.s3.eu-north-1.amazonaws.com/better-auth_ultra_detailed_interactive.html) • [Discord](https://discord.gg/better-auth) • [GitHub](https://github.com/better-auth/better-auth) [![Diagram](https://img.shields.io/badge/Diagram-2b3137?style=flat-square)](https://repodiagrams.s3.eu-north-1.amazonaws.com/better-auth_ultra_detailed_interactive.html) [![Join](https://img.shields.io/badge/join-5865F2?logo=discord&logoColor=white&style=flat-square)](https://discord.gg/better-auth) [![Star](https://img.shields.io/badge/star-181717?logo=github&logoColor=white&style=flat-square)](https://github.com/better-auth/better-auth)
GiteaMirror commented 2026-03-13 09:37:13 -05:00
Author
Owner
Copy Link

@ChristianIvicevic commented on GitHub (Oct 31, 2025):

A temporary fix for this is the use of type-fest such as this:

import { betterAuth } from 'better-auth'
import { admin } from 'better-auth/plugins'
import type { UndefinedOnPartialDeep } from 'type-fest'

const auth = betterAuth({
	plugins: [admin() as UndefinedOnPartialDeep<ReturnType<typeof admin>>],
})

This is an escape hatch and should not be necessary long-term.

@ChristianIvicevic commented on GitHub (Oct 31, 2025): A **temporary** fix for this is the use of `type-fest` such as this: ```ts import { betterAuth } from 'better-auth' import { admin } from 'better-auth/plugins' import type { UndefinedOnPartialDeep } from 'type-fest' const auth = betterAuth({ plugins: [admin() as UndefinedOnPartialDeep<ReturnType<typeof admin>>], }) ``` This is an escape hatch and should not be necessary long-term.
GiteaMirror commented 2026-03-13 09:37:14 -05:00
Author
Owner
Copy Link

@better-auth-agent[bot] commented on GitHub (Oct 31, 2025):

It appears that the issue is caused by the change in how hook types are defined in the admin plugin—specifically, the header values in the context might now be undefined, whereas the plugin’s types expect them to be a non‑optional Headers instance. This behavior was not present in version 1.3.27, making it a regression in 1.3.28.

Next steps:

  1. For a temporary workaround, you can cast the result of admin() (as shown in your example) using a helper type like UndefinedOnPartialDeep from type‑fest. This escapes the type error until a proper fix is released [1].

  2. In parallel, you could either downgrade to version 1.3.27 or submit an issue/PR to update the admin plugin’s type definitions so that the hooks (or at least the headers field) properly allow for undefined values. This should ensure that the plugin’s hook types align with what’s returned at runtime [1].

  3. Double‑check your usage of the hooks to ensure that if headers can indeed be undefined, your logic handles that scenario safely.

These steps should help you move forward until a long‑term fix is provided by the maintainers.

Diagram • Discord • GitHub

Diagram Join Star

@better-auth-agent[bot] commented on GitHub (Oct 31, 2025): It appears that the issue is caused by the change in how hook types are defined in the admin plugin—specifically, the header values in the context might now be undefined, whereas the plugin’s types expect them to be a non‑optional Headers instance. This behavior was not present in version 1.3.27, making it a regression in 1.3.28. Next steps: 1. For a temporary workaround, you can cast the result of admin() (as shown in your example) using a helper type like UndefinedOnPartialDeep from type‑fest. This escapes the type error until a proper fix is released [[1]](https://github.com/better-auth/better-auth/issues/5674). 2. In parallel, you could either downgrade to version 1.3.27 or submit an issue/PR to update the admin plugin’s type definitions so that the hooks (or at least the headers field) properly allow for undefined values. This should ensure that the plugin’s hook types align with what’s returned at runtime [[1]](https://github.com/better-auth/better-auth/issues/5674). 3. Double‑check your usage of the hooks to ensure that if headers can indeed be undefined, your logic handles that scenario safely. These steps should help you move forward until a long‑term fix is provided by the maintainers. <!-- bot:webhook reply v1 --> [Diagram](https://repodiagrams.s3.eu-north-1.amazonaws.com/better-auth_ultra_detailed_interactive.html) • [Discord](https://discord.gg/better-auth) • [GitHub](https://github.com/better-auth/better-auth) [![Diagram](https://img.shields.io/badge/Diagram-2b3137?style=flat-square)](https://repodiagrams.s3.eu-north-1.amazonaws.com/better-auth_ultra_detailed_interactive.html) [![Join](https://img.shields.io/badge/join-5865F2?logo=discord&logoColor=white&style=flat-square)](https://discord.gg/better-auth) [![Star](https://img.shields.io/badge/star-181717?logo=github&logoColor=white&style=flat-square)](https://github.com/better-auth/better-auth)
GiteaMirror commented 2026-03-13 09:37:14 -05:00
Author
Owner
Copy Link

@lensbart commented on GitHub (Nov 1, 2025):

Same for apiKey plugin

@lensbart commented on GitHub (Nov 1, 2025): Same for `apiKey` plugin
GiteaMirror commented 2026-03-13 09:37:16 -05:00
Author
Owner
Copy Link

@better-auth-agent[bot] commented on GitHub (Nov 1, 2025):

It looks like the recent update in version 1.3.28 introduced stricter type definitions for hooks (specifically for the headers property) so that a possibly undefined headers value now causes a type error. This change is affecting both the admin and the apiKey plugins.

For troubleshooting, you can try the following next steps:

  1. Confirm that your hook implementations always supply a valid Headers instance instead of leaving headers undefined. For example, provide a default value (like new Headers()) if headers might be missing.
  2. If you need an immediate workaround, you might temporarily cast the plugin to the expected type (or downgrade to version 1.3.27) until an official fix is released.
  3. Report your findings (if not already reported) and track updates on the repository so that a patch can be provided, as similar issues have been seen with hook types that require explicit handling of undefined values [1][2].

These steps should help you mitigate the regression while the maintainers work on a long‑term solution.

Diagram • Discord • GitHub

Diagram Join Star

@better-auth-agent[bot] commented on GitHub (Nov 1, 2025): It looks like the recent update in version 1.3.28 introduced stricter type definitions for hooks (specifically for the headers property) so that a possibly undefined headers value now causes a type error. This change is affecting both the admin and the apiKey plugins. For troubleshooting, you can try the following next steps: 1. Confirm that your hook implementations always supply a valid Headers instance instead of leaving headers undefined. For example, provide a default value (like new Headers()) if headers might be missing. 2. If you need an immediate workaround, you might temporarily cast the plugin to the expected type (or downgrade to version 1.3.27) until an official fix is released. 3. Report your findings (if not already reported) and track updates on the repository so that a patch can be provided, as similar issues have been seen with hook types that require explicit handling of undefined values [[1]](https://github.com/better-auth/better-auth/issues/5674)[[2]](https://github.com/better-auth/better-auth/issues/1578). These steps should help you mitigate the regression while the maintainers work on a long‑term solution. <!-- bot:webhook reply v1 --> [Diagram](https://repodiagrams.s3.eu-north-1.amazonaws.com/better-auth_ultra_detailed_interactive.html) • [Discord](https://discord.gg/better-auth) • [GitHub](https://github.com/better-auth/better-auth) [![Diagram](https://img.shields.io/badge/Diagram-2b3137?style=flat-square)](https://repodiagrams.s3.eu-north-1.amazonaws.com/better-auth_ultra_detailed_interactive.html) [![Join](https://img.shields.io/badge/join-5865F2?logo=discord&logoColor=white&style=flat-square)](https://discord.gg/better-auth) [![Star](https://img.shields.io/badge/star-181717?logo=github&logoColor=white&style=flat-square)](https://github.com/better-auth/better-auth)
GiteaMirror commented 2026-03-13 09:37:17 -05:00
Author
Owner
Copy Link

@himself65 commented on GitHub (Nov 1, 2025):

I beliebe we have fixed this in 1.4

@himself65 commented on GitHub (Nov 1, 2025): I beliebe we have fixed this in 1.4
GiteaMirror commented 2026-03-13 09:37:17 -05:00
Author
Owner
Copy Link

@better-auth-agent[bot] commented on GitHub (Nov 1, 2025):

Based on the reported regression (the admin plugin’s hooks throwing type errors in v1.3.28 due to possibly undefined headers) and the note that this has been fixed in version 1.4, the recommended next step is to upgrade your Better Auth package to 1.4 (or later) and verify that the issue is resolved on your end [1].

Make sure to update your package.json and reinstall your dependencies. After upgrading, double-check your TypeScript configuration (especially if you’re using strict options) to ensure that the new types are correctly applied. If you run into any further issues following the upgrade, please provide a minimal reproduction so we can assist further.

Diagram • Discord • GitHub

Diagram Join Star

@better-auth-agent[bot] commented on GitHub (Nov 1, 2025): Based on the reported regression (the admin plugin’s hooks throwing type errors in v1.3.28 due to possibly undefined headers) and the note that this has been fixed in version 1.4, the recommended next step is to upgrade your Better Auth package to 1.4 (or later) and verify that the issue is resolved on your end [[1]](https://github.com/better-auth/better-auth/issues/5674). Make sure to update your package.json and reinstall your dependencies. After upgrading, double-check your TypeScript configuration (especially if you’re using strict options) to ensure that the new types are correctly applied. If you run into any further issues following the upgrade, please provide a minimal reproduction so we can assist further. <!-- bot:webhook reply v1 --> [Diagram](https://repodiagrams.s3.eu-north-1.amazonaws.com/better-auth_ultra_detailed_interactive.html) • [Discord](https://discord.gg/better-auth) • [GitHub](https://github.com/better-auth/better-auth) [![Diagram](https://img.shields.io/badge/Diagram-2b3137?style=flat-square)](https://repodiagrams.s3.eu-north-1.amazonaws.com/better-auth_ultra_detailed_interactive.html) [![Join](https://img.shields.io/badge/join-5865F2?logo=discord&logoColor=white&style=flat-square)](https://discord.gg/better-auth) [![Star](https://img.shields.io/badge/star-181717?logo=github&logoColor=white&style=flat-square)](https://github.com/better-auth/better-auth)
GiteaMirror commented 2026-03-13 09:37:18 -05:00
Author
Owner
Copy Link

@ChristianIvicevic commented on GitHub (Nov 1, 2025):

I beliebe we have fixed this in 1.4

I tried out 1.4 and it seems to be fixed for the admin plugin specifically, but there is another regression due to types not being able to be named without a reference mentioned in #5574 and most notably the comment here: https://github.com/better-auth/better-auth/issues/5574#issuecomment-3456341626

For as long as that other bug is not fixed and 1.4 is not marked as stable, users have to stay on 1.3.27 for now.

@ChristianIvicevic commented on GitHub (Nov 1, 2025): > I beliebe we have fixed this in 1.4 I tried out 1.4 and it seems to be fixed for the `admin` plugin specifically, but there is another regression due to types not being able to be named without a reference mentioned in #5574 and most notably the comment here: https://github.com/better-auth/better-auth/issues/5574#issuecomment-3456341626 For as long as that other bug is not fixed and 1.4 is not marked as stable, users have to stay on 1.3.27 for now.
GiteaMirror commented 2026-03-13 09:37:18 -05:00
Author
Owner
Copy Link

@better-auth-agent[bot] commented on GitHub (Nov 1, 2025):

It looks like we’ve already fixed the admin plugin hook types error in version 1.4. However, version 1.4 still triggers another issue related to unnamed or referenced types (as noted in the linked issue discussion). Until that secondary bug is resolved and 1.4 is officially declared stable, your best workaround is to continue using 1.3.27 for production use.

Next steps:

  1. Use 1.3.27 for now if you need a stable experience without the additional type reference problems.
  2. Meanwhile, keep an eye on the repository issue (see the comment in the referenced issue) for updates on the unnamed type reference bug.
  3. Once the secondary issue is fixed and 1.4 is marked stable, upgrade to take advantage of the resolved admin plugin hooks regression.

This approach should avoid the new regression until all type issues are resolved [1][2].

Diagram • Discord • GitHub

Diagram Join Star

@better-auth-agent[bot] commented on GitHub (Nov 1, 2025): It looks like we’ve already fixed the admin plugin hook types error in version 1.4. However, version 1.4 still triggers another issue related to unnamed or referenced types (as noted in the linked issue discussion). Until that secondary bug is resolved and 1.4 is officially declared stable, your best workaround is to continue using 1.3.27 for production use. Next steps: 1. Use 1.3.27 for now if you need a stable experience without the additional type reference problems. 2. Meanwhile, keep an eye on the repository issue (see the comment in the referenced issue) for updates on the unnamed type reference bug. 3. Once the secondary issue is fixed and 1.4 is marked stable, upgrade to take advantage of the resolved admin plugin hooks regression. This approach should avoid the new regression until all type issues are resolved [[1]](https://github.com/better-auth/better-auth/issues/5674)[[2]](https://github.com/better-auth/better-auth/issues/1578). <!-- bot:webhook reply v1 --> [Diagram](https://repodiagrams.s3.eu-north-1.amazonaws.com/better-auth_ultra_detailed_interactive.html) • [Discord](https://discord.gg/better-auth) • [GitHub](https://github.com/better-auth/better-auth) [![Diagram](https://img.shields.io/badge/Diagram-2b3137?style=flat-square)](https://repodiagrams.s3.eu-north-1.amazonaws.com/better-auth_ultra_detailed_interactive.html) [![Join](https://img.shields.io/badge/join-5865F2?logo=discord&logoColor=white&style=flat-square)](https://discord.gg/better-auth) [![Star](https://img.shields.io/badge/star-181717?logo=github&logoColor=white&style=flat-square)](https://github.com/better-auth/better-auth)
GiteaMirror commented 2026-03-13 09:37:19 -05:00
Author
Owner
Copy Link

@himself65 commented on GitHub (Nov 4, 2025):

We have fixed this in 1.3, latest I believe? and also be fixed in 1.4 beta

@himself65 commented on GitHub (Nov 4, 2025): We have fixed this in 1.3, latest I believe? and also be fixed in 1.4 beta
GiteaMirror commented 2026-03-13 09:37:19 -05:00
Author
Owner
Copy Link

@better-auth-agent[bot] commented on GitHub (Nov 4, 2025):

(tag @better-auth-agent) Could you please confirm if you’re still encountering this issue with version 1.3.28, or if upgrading to 1.3.27 or the 1.4 beta build resolves the type error with the admin plugin hooks? I'm happy to help troubleshoot further!

Diagram • Discord • GitHub

Diagram Join Star

@better-auth-agent[bot] commented on GitHub (Nov 4, 2025): (tag @better-auth-agent) Could you please confirm if you’re still encountering this issue with version 1.3.28, or if upgrading to 1.3.27 or the 1.4 beta build resolves the type error with the admin plugin hooks? I'm happy to help troubleshoot further! <!-- bot:webhook reply v1 --> [Diagram](https://repodiagrams.s3.eu-north-1.amazonaws.com/better-auth_ultra_detailed_interactive.html) • [Discord](https://discord.gg/better-auth) • [GitHub](https://github.com/better-auth/better-auth) [![Diagram](https://img.shields.io/badge/Diagram-2b3137?style=flat-square)](https://repodiagrams.s3.eu-north-1.amazonaws.com/better-auth_ultra_detailed_interactive.html) [![Join](https://img.shields.io/badge/join-5865F2?logo=discord&logoColor=white&style=flat-square)](https://discord.gg/better-auth) [![Star](https://img.shields.io/badge/star-181717?logo=github&logoColor=white&style=flat-square)](https://github.com/better-auth/better-auth)
GiteaMirror commented 2026-03-13 09:37:20 -05:00
Author
Owner
Copy Link

@ChristianIvicevic commented on GitHub (Nov 4, 2025):

We have fixed this in 1.3, latest I believe? and also be fixed in 1.4 beta

No, this is not fixed in 1.3.34.
Only in 1.4 which itself is not yet stable and has other regressions.

@ChristianIvicevic commented on GitHub (Nov 4, 2025): > We have fixed this in 1.3, latest I believe? and also be fixed in 1.4 beta No, this is not fixed in 1.3.34. Only in 1.4 which itself is not yet stable and has other regressions.
GiteaMirror commented 2026-03-13 09:37:21 -05:00
Author
Owner
Copy Link

@better-auth-agent[bot] commented on GitHub (Nov 4, 2025):

Hi there! We’re aware of the regression with the admin plugin hooks that you’re experiencing in version 1.3.28. In 1.3.27, the hooks worked as expected without this type error, and our team has fixed the issue in the 1.4 beta release. However, we understand that the beta isn’t stable for your use case and that you’re seeing additional regressions there.

For next steps, you might consider rolling back to version 1.3.27 if you need a stable setup in the meantime. Alternatively, if you’re able to test in a controlled environment, you could try the 1.4 beta while reporting any further issues you encounter so we can address them as quickly as possible [1] (this is based on the feedback that the fix landed in 1.4 beta).

Can you share any additional details about the regressions you’ve seen in 1.4 beta? This would help us ensure we address all related issues.

tag @better-auth-agent

Diagram • Discord • GitHub

Diagram Join Star

@better-auth-agent[bot] commented on GitHub (Nov 4, 2025): Hi there! We’re aware of the regression with the admin plugin hooks that you’re experiencing in version 1.3.28. In 1.3.27, the hooks worked as expected without this type error, and our team has fixed the issue in the 1.4 beta release. However, we understand that the beta isn’t stable for your use case and that you’re seeing additional regressions there. For next steps, you might consider rolling back to version 1.3.27 if you need a stable setup in the meantime. Alternatively, if you’re able to test in a controlled environment, you could try the 1.4 beta while reporting any further issues you encounter so we can address them as quickly as possible [[1]](https://github.com/better-auth/better-auth/issues/4125) (this is based on the feedback that the fix landed in 1.4 beta). Can you share any additional details about the regressions you’ve seen in 1.4 beta? This would help us ensure we address all related issues. tag @better-auth-agent <!-- bot:webhook reply v1 --> [Diagram](https://repodiagrams.s3.eu-north-1.amazonaws.com/better-auth_ultra_detailed_interactive.html) • [Discord](https://discord.gg/better-auth) • [GitHub](https://github.com/better-auth/better-auth) [![Diagram](https://img.shields.io/badge/Diagram-2b3137?style=flat-square)](https://repodiagrams.s3.eu-north-1.amazonaws.com/better-auth_ultra_detailed_interactive.html) [![Join](https://img.shields.io/badge/join-5865F2?logo=discord&logoColor=white&style=flat-square)](https://discord.gg/better-auth) [![Star](https://img.shields.io/badge/star-181717?logo=github&logoColor=white&style=flat-square)](https://github.com/better-auth/better-auth)
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
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#2235
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?