[GH-ISSUE #1119] Insufficient documentation about baseUrl/BETTER_AUTH_URL and non-working config #8604

New Issue

GiteaMirror · 2026-04-13T03:43:14-05:00

GiteaMirror commented

2026-04-13 03:43:14 -05:00

Originally created by @JosipPardon on GitHub (Jan 4, 2025).
Original GitHub issue: https://github.com/better-auth/better-auth/issues/1119

Is this suited for github?

Yes, this is suited for github

To Reproduce

I tried really hard to understand what baseUrl and BETTER_AUTH_URL are used for, but I eventually gave up. I know that baseUrl in authClient tells authClient where requests should be sent, but server side remains boggling to me.

I tried intentionally setting baseUrl and BETTER_AUTH_URL to incorrect values, but everything continued to work totally fine (on local dev server). How?! My server was running at http://localhost:3000 and I set both values to be http://localhost:1234 or something like that.

I think that these values tell auth.api where to send requests. In that case, it does not make sense to use https://mydomain.com because unnecessary DNS requests will be sent, http://localhost:3000 should be used in both production and dev environments.

But I suppose this is not what these values are used for...

Docs should describe this in much more detail. It should be stated exactly how baseUrl and BETTER_AUTH_URL are used under the hood so that we can determine which values to use in different environments.

Current vs. Expected behavior

Described above

What version of Better Auth are you using?

1.1.8

Provide environment information

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

Documentation, Package

Auth config (if applicable)

No response

Additional context

No response

Originally created by @JosipPardon on GitHub (Jan 4, 2025). Original GitHub issue: https://github.com/better-auth/better-auth/issues/1119 ### Is this suited for github? - [X] Yes, this is suited for github ### To Reproduce I tried really hard to understand what `baseUrl` and `BETTER_AUTH_URL` are used for, but I eventually gave up. I know that `baseUrl` in `authClient` tells `authClient` where requests should be sent, but server side remains boggling to me. I tried intentionally setting `baseUrl` and `BETTER_AUTH_URL` to incorrect values, but everything continued to work totally fine (on local dev server). How?! My server was running at `http://localhost:3000` and I set both values to be `http://localhost:1234` or something like that. I think that these values tell `auth.api` where to send requests. In that case, it does not make sense to use `https://mydomain.com` because unnecessary DNS requests will be sent, `http://localhost:3000` should be used in both production and dev environments. But I suppose this is not what these values are used for... Docs should describe this in much more detail. It should be stated exactly how `baseUrl` and `BETTER_AUTH_URL` are used under the hood so that we can determine which values to use in different environments. ### Current vs. Expected behavior Described above ### What version of Better Auth are you using? 1.1.8 ### Provide environment information ```bash - ``` ### Which area(s) are affected? (Select all that apply) Documentation, Package ### Auth config (if applicable) _No response_ ### Additional context _No response_

GiteaMirror added the locked label 2026-04-13 03:43:14 -05:00

GiteaMirror closed this issue

2026-04-13 03:43:15 -05:00

GiteaMirror commented

2026-04-13 03:43:16 -05:00

@moshetanzer commented on GitHub (Mar 23, 2025):

Hey,

Are you using oauth or email and password?

@moshetanzer commented on GitHub (Mar 23, 2025): Hey, Are you using oauth or email and password?

GiteaMirror commented

2026-04-13 03:43:17 -05:00

@JosipPardon commented on GitHub (Mar 24, 2025):

Hi @moshetanzer

Thanks for the response!

I prefer to have email OTP and Google for auth in my apps with BetterAuth.

But I don't understand how is that relevant to this issue. Problem is that baseUrl and BETTER_AUTH_URL are not sufficiently described how they work under the hood, regardless of which auth type we are using.

@JosipPardon commented on GitHub (Mar 24, 2025): Hi @moshetanzer Thanks for the response! I prefer to have email OTP and Google for auth in my apps with BetterAuth. But I don't understand how is that relevant to this issue. Problem is that `baseUrl` and `BETTER_AUTH_URL` are not sufficiently described how they work under the hood, regardless of which auth type we are using.

GiteaMirror commented

2026-04-13 03:43:18 -05:00

@lord007tn commented on GitHub (Mar 24, 2025):

same problem here
I end up giving up on better-auth for our company project and was inspired by it to build a custom one for us

the problem when you have separation between frontend and backend apps ( our case, nextjs in frontend, honojs in backend )

Google auth seems to work until the part of callback when it always redirect to the backend with non valid path always to /

and according to docs, it should redirect to /google/callback to handle it properly

there are other problems that I manage to go around, especially with prisma and people already mentioning them but still no fix

I am not hating nor telling you that better auth is not ready, but for a complex structure monorepo app it can't do the job fine

always going back to see what have been fixed over time and the progress of the library.

@lord007tn commented on GitHub (Mar 24, 2025): same problem here I end up giving up on better-auth for our company project and was inspired by it to build a custom one for us the problem when you have separation between frontend and backend apps ( our case, nextjs in frontend, honojs in backend ) Google auth seems to work until the part of callback when it always redirect to the backend with non valid path always to / and according to docs, it should redirect to /google/callback to handle it properly there are other problems that I manage to go around, especially with prisma and people already mentioning them but still no fix I am not hating nor telling you that better auth is not ready, but for a complex structure monorepo app it can't do the job fine always going back to see what have been fixed over time and the progress of the library.

GiteaMirror commented

2026-04-13 03:43:19 -05:00

@moshetanzer commented on GitHub (Mar 24, 2025):

Hey @lord007tn not sure exactly what your issue is. Feel free to open another issue with reproduction - at first glance seems like more of a question than a bug.

@JosipPardon will try get some more docs on it. As far as I understand is that it tried to auto detect base for things like oauth callback, but if for example you using a separate front end and server and it is unable to detect than you have the ability to set correct base url. Could be wrong though @Bekacru is this correct?

@moshetanzer commented on GitHub (Mar 24, 2025): Hey @lord007tn not sure exactly what your issue is. Feel free to open another issue with reproduction - at first glance seems like more of a question than a bug. @JosipPardon will try get some more docs on it. As far as I understand is that it tried to auto detect base for things like oauth callback, but if for example you using a separate front end and server and it is unable to detect than you have the ability to set correct base url. Could be wrong though @Bekacru is this correct?

GiteaMirror commented

2026-04-13 03:43:19 -05:00

@Bekacru commented on GitHub (Mar 24, 2025):

I'm not sure what's hard to understand about baseURL. Basically, it tells the server what URL it is currently running on. If the request comes from a client, the server can detect this from the request URL or forwarded headers. However, if no request is present, it will use the baseURL to determine things like routing, whether it's running on HTTPS (to set secure cookies), and which URLs to include or exclude. Also, in case the calls you're making are initiated by auth.api, they are mostly not affected by baseURL

@Bekacru commented on GitHub (Mar 24, 2025): I'm not sure what's hard to understand about baseURL. Basically, it tells the server what URL it is currently running on. If the request comes from a client, the server can detect this from the request URL or forwarded headers. However, if no request is present, it will use the baseURL to determine things like routing, whether it's running on HTTPS (to set secure cookies), and which URLs to include or exclude. Also, in case the calls you're making are initiated by `auth.api`, they are mostly not affected by baseURL

GiteaMirror commented

2026-04-13 03:43:20 -05:00

@RaeesBhatti commented on GitHub (Jun 2, 2025):

An app could be running on ten different URLs at the same time. e.g. an app deployed on Vercel might have a couple of custom domain names, deployment id sub domain, and environment sub domain. It's not practical to change the environment variable on every deployment or even change the value of baseUrl parameter since betterAuth() instance is created once and reused; and the URL might not be known at startup time.
I would suggest that baseUrl parameter be changed to accept a function that takes a Request as parameter and returns a URL, similar to trustedOrigins parameter. This will allow developers to derive baseUrl from the received request (taking x-forwarded-host, etc into account).

@RaeesBhatti commented on GitHub (Jun 2, 2025): An app could be running on ten different URLs at the same time. e.g. an app deployed on Vercel might have a couple of custom domain names, deployment id sub domain, and environment sub domain. It's not practical to change the environment variable on every deployment or even change the value of `baseUrl` parameter since `betterAuth()` instance is created once and reused; and the URL might not be known at startup time. I would suggest that `baseUrl ` parameter be changed to accept a function that takes a `Request` as parameter and returns a URL, similar to `trustedOrigins` parameter. This will allow developers to derive `baseUrl` from the received request (taking `x-forwarded-host`, etc into account).

GiteaMirror commented

2026-04-13 03:43:21 -05:00

@Stadly commented on GitHub (Aug 22, 2025):

@RaeesBhatti Very good idea! I created a separate issue with your idea, since this issue is mainly concerning documentation.

https://github.com/better-auth/better-auth/issues/4151

@Stadly commented on GitHub (Aug 22, 2025): @RaeesBhatti Very good idea! I created a separate issue with your idea, since this issue is mainly concerning documentation. https://github.com/better-auth/better-auth/issues/4151

GiteaMirror commented

2026-04-13 03:43:21 -05:00

@moshetanzer commented on GitHub (Aug 22, 2025):

@Stadly @RaeesBhatti Vercel has a env url with current deployment url available. Most platforms have this I think. You should never have to set manually.

See https://vercel.com/docs/environment-variables/system-environment-variables

@moshetanzer commented on GitHub (Aug 22, 2025): @Stadly @RaeesBhatti Vercel has a env url with current deployment url available. Most platforms have this I think. You should never have to set manually. See https://vercel.com/docs/environment-variables/system-environment-variables

GiteaMirror commented

2026-04-13 03:43:22 -05:00

@Stadly commented on GitHub (Aug 22, 2025):

I'm using SvelteKit, and I have to set baseUrl in order to use the Microsoft social provider in my local development envionment. I have not tested it when deployed yet.

@Stadly commented on GitHub (Aug 22, 2025): I'm using SvelteKit, and I have to set `baseUrl` in order to use the Microsoft social provider in my local development envionment. I have not tested it when deployed yet.

GiteaMirror commented

2026-04-13 03:43:23 -05:00

@himself65 commented on GitHub (Aug 23, 2025):

I'm checking this recently and debugging the Vercel preview environment. And I, yeah, I have the same problem with you guys at the beginning.

The baseURL would affect where we store the cookie; if it's in the wrong domain, the user session will not be stored. So that most of the logic relies on cookies (like useSession) will just be unauthenticated. You should always check the API response for set-cookie to have the right domain.

And my fix for the Vercel preview:

d476fbed07/demo/nextjs/lib/auth.ts (L52-L68)

But yeah, we should improve the document and UX to help developers address this pitfall.

@himself65 commented on GitHub (Aug 23, 2025): I'm checking this recently and debugging the Vercel preview environment. And I, yeah, I have the same problem with you guys at the beginning. The baseURL would affect where we store the cookie; if it's in the wrong domain, the user session will not be stored. So that most of the logic relies on cookies (like `useSession`) will just be unauthenticated. You should always check the API response for `set-cookie` to have the right domain. And my fix for the Vercel preview: https://github.com/better-auth/better-auth/blob/d476fbed074253121df0e23414bd059c93274553/demo/nextjs/lib/auth.ts#L52-L68 But yeah, we should improve the document and UX to help developers address this pitfall.

GiteaMirror commented

2026-04-13 03:43:24 -05:00

@RaeesBhatti commented on GitHub (Aug 23, 2025):

@Stadly @RaeesBhatti Vercel has a env url with current deployment url available. Most platforms have this I think. You should never have to set manually.

See https://vercel.com/docs/environment-variables/system-environment-variables

Thank you for the correction. I might have been wrong about Vercel's implementation of this but those env vars might not be available for Next.js or other frameworks outside of Vercel.
I think we should focus on the principle rather than a platform's implementation: should Better-Auth be usable on multiple different hostnames running on the same app process. I think yes.

@RaeesBhatti commented on GitHub (Aug 23, 2025): > [@Stadly](https://github.com/Stadly) [@RaeesBhatti](https://github.com/RaeesBhatti) Vercel has a env url with current deployment url available. Most platforms have this I think. You should never have to set manually. > > See https://vercel.com/docs/environment-variables/system-environment-variables Thank you for the correction. I might have been wrong about Vercel's implementation of this but those env vars might not be available for Next.js or other frameworks outside of Vercel. I think we should focus on the principle rather than a platform's implementation: should Better-Auth be usable on multiple different hostnames running on the same app process. I think yes.

GiteaMirror commented

2026-04-13 03:43:24 -05:00

@Stadly commented on GitHub (Aug 24, 2025):

This would also be useful in other scenarios than running the same app on multiple hostnames. For example, the Vite dev server uses port 5173 by default. If that port is taken, it spins up on port 5174, etc. When developing on multiple apps, or using git worktrees, the port the app is running on might therefore not always be the same (since multiple dev servers might be running at the same time). Currently, the developer must then change the baseUrl based on which port the dev server is currently using.

@Stadly commented on GitHub (Aug 24, 2025): This would also be useful in other scenarios than running the same app on multiple hostnames. For example, the Vite dev server uses port 5173 by default. If that port is taken, it spins up on port 5174, etc. When developing on multiple apps, or using git worktrees, the port the app is running on might therefore not always be the same (since multiple dev servers might be running at the same time). Currently, the developer must then change the `baseUrl` based on which port the dev server is currently using.

GiteaMirror commented

2026-04-13 03:43:25 -05:00

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

Couldn't agree more with the feedback provided here.
I've spent too much time debugging confirmation emails on Vercel preview links because the confirmation URL didn't contain the baseUrl. Which is super weird because for change email it did contain the complete URL but not for email verification.

I would love to see an example configuration on the docs that works both locally and on Vercel.

@Cali93 commented on GitHub (Nov 4, 2025): Couldn't agree more with the feedback provided here. I've spent too much time debugging confirmation emails on Vercel preview links because the confirmation URL didn't contain the `baseUrl`. Which is super weird because for change email it did contain the complete URL but not for email verification. I would love to see an example configuration on the docs that works both locally and on Vercel.

GiteaMirror commented

2026-04-13 03:43:26 -05:00

@dosubot[bot] commented on GitHub (Feb 3, 2026):

Hi, @JosipPardon. I'm Dosu, and I'm helping the better-auth team manage their backlog and am marking this issue as stale.

Issue Summary:

You raised concerns about unclear documentation regarding baseUrl and BETTER_AUTH_URL in Better Auth.
It was clarified that baseUrl is used by the server to determine its running URL when no request context is available, impacting routing and secure cookies.
Other users shared difficulties with multi-host setups and suggested enhancements like allowing baseUrl to be a function for dynamic URL resolution.
A separate issue was created to track the feature request for dynamic baseUrl handling.
The core need remains clearer documentation and improved support for dynamic environments such as Vercel and local development.

Next Steps:

Please let me know if this issue is still relevant with the latest version of better-auth by commenting here to keep the discussion open.
If I don’t hear back within 7 days, I will automatically close this issue to help us focus on active items.

Thanks for your understanding and contribution!

@dosubot[bot] commented on GitHub (Feb 3, 2026): Hi, @JosipPardon. I'm [Dosu](https://dosu.dev), and I'm helping the better-auth team manage their backlog and am marking this issue as stale. **Issue Summary:** - You raised concerns about unclear documentation regarding `baseUrl` and `BETTER_AUTH_URL` in Better Auth. - It was clarified that `baseUrl` is used by the server to determine its running URL when no request context is available, impacting routing and secure cookies. - Other users shared difficulties with multi-host setups and suggested enhancements like allowing `baseUrl` to be a function for dynamic URL resolution. - A separate issue was created to track the feature request for dynamic `baseUrl` handling. - The core need remains clearer documentation and improved support for dynamic environments such as Vercel and local development. **Next Steps:** - Please let me know if this issue is still relevant with the latest version of better-auth by commenting here to keep the discussion open. - If I don’t hear back within 7 days, I will automatically close this issue to help us focus on active items. Thanks for your understanding and contribution!

GiteaMirror commented

2026-04-13 03:43:27 -05:00

@github-actions[bot] commented on GitHub (Apr 1, 2026):

This issue has been locked as it was closed more than 7 days ago. If you're experiencing a similar problem or you have additional context, please open a new issue and reference this one.

@github-actions[bot] commented on GitHub (Apr 1, 2026): This issue has been locked as it was closed more than 7 days ago. If you're experiencing a similar problem or you have additional context, please open a new issue and reference this one.

GiteaMirror referenced this issue

2026-04-13 07:30:11 -05:00

[GH-ISSUE #8604] `useActiveMemberRole` does not return `owner` role, although saved in db row. #11133

GiteaMirror referenced this issue

2026-04-13 10:29:56 -05:00

[PR #8613] fix(sso): include owner role in organization provisioning types #16345

GiteaMirror referenced this issue

2026-04-15 17:09:36 -05:00

[GH-ISSUE #4557] Dynamic Roles and Permissions for Admin Plugin #18612

GiteaMirror referenced this issue

2026-04-15 19:06:10 -05:00

[GH-ISSUE #8604] `useActiveMemberRole` does not return `owner` role, although saved in db row. #19764

GiteaMirror referenced this issue

2026-04-15 22:41:01 -05:00

[PR #8613] fix(sso): include owner role in organization provisioning types #24999

GiteaMirror referenced this issue

2026-04-17 18:14:20 -05:00

[GH-ISSUE #4557] Dynamic Roles and Permissions for Admin Plugin #27304

GiteaMirror referenced this issue

2026-04-17 19:54:07 -05:00

[GH-ISSUE #8604] `useActiveMemberRole` does not return `owner` role, although saved in db row. #28456

Sign in to join this conversation.

Branches Tags

2026-05-22/chore/adopt-agents-md

2026-05-22/refactor/string-case-utils

dependabot/npm_and_yarn/uuid-14.0.0

dependabot/npm_and_yarn/turbo-2.9.14

changeset-release/main

main

2026-05-14/fix/passkey-verify-error-and-claim

dependabot/npm_and_yarn/samlify-2.13.0

dependabot/npm_and_yarn/ws-8.20.1

changeset-release/next

dependabot/npm_and_yarn/demo/electron/demo-minor-patch-519ef7475f

dependabot/github_actions/github-actions-98f3470200

client-assertions-main

2026-05-15/ci/fix-sqlite-abi-mismatch

2026-05-15/fix/organization-team-add-cascade

2026-05-15/fix/parse-set-cookie-value-validation

2026-05-13/feat/captcha-wildcard-endpoints

2026-05-13/ci/stabilize-docker-startup

fix/i18n-before-hook-translation

fix/disable-migration-generate

2026-05-07/fix/admin-set-password-upsert

2026-05-10/fix/cookie-drain-order

2026-05-10/feat/hooks-finally

2026-05-09/fix/cookie-drain-order

2026-05-09/feat/hooks-finally

2026-05-08/feat/register-before-send

fix/stripe/subscription-data-merge

2026-05-01/chore/pnpm-v11-harden

chore/pnpm-v11

2026-04-29/feat/google-include-granted-scopes

2026-04-29/fix/oauth-account-scope-semantics

2026-04-27/fix/nextcookies-idempotent-writes

2026-04-26/fix/harden-proxy-host-validation

2026-04-26/refactor/stripe-callback-signature-cleanup

2026-04-26/fix/stripe-subscription-callback-timing

2026-04-11/fix/sveltekit-app-modules

feat/open-api-zod-contract

feat/oauth-provider-backchannel-logout-next

feat/oauth-idp-initiated-bounce

refactor/sign-in-challenges

2026-04-21/fix/oauth-rfc-input-validation

fix/release-notes-new-packages

fix/two-factor-identity-guard

fix/resource

feat/emailpassword-authorize

2026-04-12/security/dynamic-baseurl-proxy-trust-default

feat/oauth-provider-at-hash-v2

fix/release-grep-fallback

claude/address-review-comments-JhFLr

claude/slack-update-stripe-docs-consistency-8Sc0w

feat/async-auth

fix/two-factor-totp-verified-enrollment

feat/plugin-ui

codex/blog-1-6-release-post

2026-04-06/fix/type-any-guards

2026-04-05/chore/downgrade-better-call

2026-04-04/ci/skip-vercel-fork-prs

2026-03-28/ci/add-autofix-ci

chore/release-preview-script

himself65/2026/02/19/role

2026-03-24/fix/update-user-info-on-link

2026-03-20/docs/improve-website

2026-03-20/fix/anonymous-onlinkaccount-expo

2026-02-17/fix/anonymous-link-state

fix/8607-saml-inresponseto

fix/8549-scim-patch-noop

v1.4.x

refactor/migration-snapshot-tests

worktree-magic-link-additional-data

chore/migrate-build-to-rollup

worktree-fix-dynamic-baseurl-8447

2026-03-06/chore/public-api-check

fix/close-8156-regression-test

fix/secondary-storage-json-error-handling

himself65/verification-namespace

cursor/issue-8307-validation-79a3

himself65/2026/01/30/error-mdx

v1.4.x-staging

fix/email-otp-user

fix/restrict-full-organization-access-roles

himself65/2026/02/12/count

himself65/2026/02/04/define-plugin

2026-02-04/feat/add-pluralize

cursor/better-auth-js-integration-ec21

cursor/expo-state-mismatch-394c

2026-02-01/fix/org-update-role-sync-members

cursor/issue-7607-investigation-e146

cursor/email-generation-helper-0ff6

himself65/2026/01/21/avoid-spread-operator

himself65/2026/01/14/cli

claude/slack-add-docs-pr-NMvgO

claude/slack-add-advanced-useplural-WHKYL

feat/hooks-pos

feat/2fa-phone

feat/2fa

fix/rotation

fix/username-check

v1.3.x

refactor/organization

feat/multiple-client-ids-social-providers

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: github-starred/better-auth#8604