Next Auth docs say npx auth secret gives AUTH_SECRET, but it now gives BETTER_AUTH_SECRET

[bloodykheeng]

Docs say npx auth secret gives AUTH_SECRET, but it now gives BETTER_AUTH_SECRET

Summary

Since the Auth.js and Better Auth teams came together, the auth package on npm
is Better Auth's CLI. The Auth.js installation docs still tell people to run
npx auth secret and still show AUTH_SECRET as the result, so anyone
following that guide today ends up with a variable their Auth.js app never
reads.

I hit this on a next-auth v4 project and want to be clear that I am not
reporting the handover as a problem: it is public and deliberate. The problem is
that the setup instructions were not updated with it, and the failure is silent.

Steps to reproduce

1. Follow https://authjs.dev/getting-started/installation
2. Run the command it gives you:

npx auth secret

Output:

Add the following to your .env file:
# Auth Secret
BETTER_AUTH_SECRET=<value>

The docs on that page, and on
https://authjs.dev/guides/environment-variables, say the variable is
AUTH_SECRET.

Why this is worth fixing

The failure is silent and looks like success. The command exits 0 and prints a
perfectly good secret, so the only wrong thing is the name. Nothing warns you,
and the app then behaves as though no secret were set: on v4 that surfaces much
later as a JWT decryption error that points nowhere near this step.

It is also genuinely hard to work out on your own. Two products are involved,
"Auth.js" and "Better Auth" both plausibly own a command called auth, and the
docs page that sent you there does not mention the other name at all. Someone
new to this cannot tell whether they typed something wrong, installed the wrong
package, or hit a bug.

Registry state, for reference

$ npm view auth name version description repository.url
name = 'auth'
version = '1.6.29'
description = 'The CLI for Better Auth'
repository.url = 'git+https://github.com/better-auth/better-auth.git'

$ npm view auth bin
{ auth: './dist/index.mjs', 'better-auth': './dist/index.mjs' }

nextauthjs/cli still declares "name": "auth" at "version": "1.2.3", so
npx auth resolves to the newer published one and the Auth.js CLI in this repo
is not what runs. There is also no @auth/cli to point people at instead
(npm view @auth/cli is a 404).

Related: NEXTAUTH_SECRET has no underscore, and mistyping it is silent too

Same shape of problem, one step earlier, so I am raising it here rather than
opening a second issue.

Every other environment variable a Next.js developer meets has underscores
between the words, NEXT_PUBLIC_API_URL and so on, so NEXTAUTH_SECRET reads
as a typo and gets "corrected" to NEXT_AUTH_SECRET on the way into the file.
Sitting next to BETTER_AUTH_SECRET, which does have the underscore, it looks
inconsistent rather than deliberate.

It is not inconsistent, and that is the part the docs never say: the prefix is
the product name, not a Next.js prefix. NextAuth is one word, so NEXTAUTH.
Better Auth is two, so BETTER_AUTH. Auth.js is one, so AUTH. Once someone
tells you that, all three names are obviously the same rule, and until someone
tells you, they look like three different ones.

What makes it worth fixing rather than just noting is that the mistake is silent
in exactly the same way as the one above. From next-auth@4.24.15,
core/lib/assert.js:

if (!options.secret && process.env.NODE_ENV !== "production") warnings.push("NO_SECRET");
// ...
if (!options.secret && process.env.NODE_ENV === "production") {
  return new _errors.MissingSecret("Please define a `secret` in production.");
}

So NEXT_AUTH_SECRET in .env gives a working dev server and a warning most
people scroll past, and the first real sign of trouble is production refusing to
boot. A missing NEXTAUTH_URL is a warning only, as well.

One sentence on the env vars page would close it, something like: "the prefix is
the product name, so it is NEXTAUTH_SECRET with no underscore on v4, and
AUTH_SECRET on v5."

Environment

• next-auth 4.24.15, Next.js 16.2.4
• npm 10.x, Windows 11
• Observed 16 August 2026

Suggested fix

Any one of these would have saved the confusion:

1. Update https://authjs.dev/getting-started/installation and
   https://authjs.dev/guides/environment-variables so the command shown matches
   what it now prints, with a line saying Auth.js reads AUTH_SECRET (and
   NEXTAUTH_SECRET on v4) whatever the CLI calls it.

2. Have the CLI print the Auth.js name when it detects an Auth.js or
   next-auth project, since it already detects the framework.

3. Add the dependency-free alternative next to it, which cannot drift:

   openssl rand -base64 32

4. Say on the environment variables page that the prefix is the product name,
   which is what makes NEXTAUTH_SECRET, AUTH_SECRET and BETTER_AUTH_SECRET
   one rule instead of three.