# 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"

```text
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.

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

:::callout
**The variable is `AUTH_SECRET`.** The underlying auth library names `BETTER_AUTH_SECRET` in its message, but Sovrium reads `AUTH_SECRET`. Set that one.
:::

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"

```text
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:

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

See [Environment Variables](/en/docs/env-vars) for the full set, and [Email Integration](/en/docs/integrate-email) 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"

```text
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:

```bash
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](/en/docs/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](https://github.com/sovrium/sovrium/issues) or
  [discussion](https://github.com/sovrium/sovrium/discussions).

## Related Pages

- [Troubleshooting: Startup & Config](/en/docs/troubleshooting) — errors before the server is up.
- [Environment Variables](/en/docs/env-vars) — every variable Sovrium reads.
- [Security Hardening](/en/docs/security-hardening) — secrets, rotation, and deployment posture.
- [MCP Integration](/en/docs/mcp-integration) — connecting an MCP client end to end.