Troubleshooting: Auth, Email & MCP

Once the server boots, the next class of problem comes from the services layered on top. These are the three that most often surprise people — two of them because they are warnings, not failures, and the feature simply does not work.

Auth: "You are using the default secret"

You are using the default secret. Please set `BETTER_AUTH_SECRET` in your
environment variables or pass `secret` in your auth config.

An app with authentication needs a real signing secret in production. In development it falls back to a built-in dev secret and only warns — which is why this typically shows up at deploy time, not while you were building the feature.

sovrium secret generate auth   # prints AUTH_SECRET=<64-hex>

Until it is set, sessions are signed with a key that is identical in every Sovrium install — anyone can forge one. Treat this warning as blocking for any deployment reachable from outside your machine.

"Email sending disabled — SMTP not configured"

Email sending disabled — SMTP not configured (set SMTP_HOST to enable)

A warning, not a failure — and the more dangerous for it. The app boots, sign-up succeeds, password reset returns 200. The mail is written to the log instead of sent, so the links never arrive and the flow looks broken from the user's side only.

Set SMTP_HOST and its companions to enable delivery:

SMTP_HOST=smtp.example.com
SMTP_PORT=587          # default
SMTP_USER=apikey
SMTP_PASS=<secret>

See Environment Variables for the full set, and Email Integration for provider setup. Anything with email verification or password reset should be tested against a real SMTP host before it ships.

MCP: "no token is set"

MCP env validation failed: MCP_AUTH_STRATEGY=token but no
MCP_TOKEN_ADMIN/MEMBER/VIEWER is set. At least one role token must be configured
for clients to authenticate.

You turned on the MCP server with token authentication and gave it no token, so no client could ever authenticate. Unlike the two above, this one is fatal — the server refuses to start rather than exposing an endpoint nobody can use.

Provide at least one role token, each 32 characters or longer:

MCP_TOKEN_ADMIN=$(openssl rand -hex 32)

Each role token grants that role's permissions to whoever holds it, so issue the narrowest one that works — MCP_TOKEN_VIEWER for a read-only client. See MCP Integration.

Still stuck?

• Run sovrium validate <config> to check the configuration on its own.
• An unhandled failure prints Unexpected error: with a message and an issue link. That banner means Sovrium did not anticipate the failure — copy the message into the report.
• Search the docs with ⌘K, or open a GitHub issue or discussion.

Related Pages

• Troubleshooting: Startup & Config — errors before the server is up.
• Environment Variables — every variable Sovrium reads.
• Security Hardening — secrets, rotation, and deployment posture.
• MCP Integration — connecting an MCP client end to end.