---
title: "Troubleshooting"
description: "Common problems, what causes them and how to fix them. API errors have the form { \"error\": { \"type\", \"code\", \"message\" } }; the code is listed in each heading where there is one."
url: https://onesend.email/docs/troubleshooting/
---
# Troubleshooting

Common problems, what causes them and how to fix them. API errors have the form `{ "error": { "type", "code", "message" } }`; the `code` is listed in each heading where there is one.

<a id="dashboard-not-built"></a>
## `/` shows "The dashboard is not built"

The server cannot find `apps/web/dist/index.html`, so `/` shows a short page with build instructions and links to `/docs` and `/openapi.json`. The API works normally. `npm run dev` builds the dashboard before it starts, so this happens mainly with `npm start` or `node apps/server/bin/onesend-server.mjs` on a fresh checkout.

Build it and restart the server:

```bash
npm run build:web
```

Or run the development dashboard with `npm run dev:web` and open http://localhost:5199. If you keep the build somewhere else, set `ONESEND_WEB_DIST` to that folder.

<a id="secret-errors"></a>
## The server stops at startup with an `ONESEND_SECRET` error

- **`ONESEND_SECRET (or ONESEND_SECRET_FILE) is required when NODE_ENV=production`.** Production mode does not generate a secret. Set one: `openssl rand -base64 32`. The Docker image and `.env.example` set `NODE_ENV=production`.
- **`ONESEND_SECRET must be at least 32 characters`.** Generate a new value with the command above.
- **`ONESEND_SECRET is still the placeholder from .env.example`.** Replace the value with a generated one (`openssl rand -base64 32`). Values that look like placeholders (starting with `<`, or containing `generate-with`, `changeme` or `placeholder`) are rejected, because a placeholder secret is public and anything encrypted with it would not be protected.
- **`Could not decrypt provider credentials — was ONESEND_SECRET changed?`** The secret differs from the one used to store the credentials. Restore the previous value, or set it as `ONESEND_SECRET_PREVIOUS` and follow [Rotating ONESEND_SECRET](https://onesend.email/docs/self-hosting/#rotating-onesend_secret).

<a id="sent-but-not-delivered"></a>
## An email shows `sent` but never arrives

1. Open the email in **Logs**, or call `GET /v1/emails/{id}`, and check which provider carried it.
2. If the provider is `sandbox`, nothing was delivered. A new workspace sends through the built-in **Sandbox** provider until you connect a real one. Connect a provider under **Sending providers**; Sandbox is then turned off in the default routing policy. If you edited the policy, check under **Routing** that Sandbox is not an enabled step.
3. If the status is `sandboxed`, the email was sent with a test key (`os_test_…`) or with sandbox mode turned on for the workspace. Use a live key (`os_live_…`).
4. If a real provider accepted it, check the provider's own logs, the recipient's spam folder, and the domain's DNS under **Senders & domains**. Unverified domains and missing DKIM records are the most common cause of mail going to spam or being dropped.

<a id="signup-closed"></a>
## Sign-up returns 403 `signup_closed`

`ONESEND_SIGNUP` defaults to `first-user`: only the first account on the instance can sign up. With `closed`, nobody can sign up over the network, and the owner account of a fresh instance must be created from the server itself (`http://localhost:<port>` on that machine, or through an SSH tunnel).

To add people to your workspace, invite them under **Settings → Team → Invite**: someone without an account creates one on the invitation page, whatever `ONESEND_SIGNUP` is (see [Invitations](https://onesend.email/docs/team/#invitations)). Set `ONESEND_SIGNUP=open` only when anyone who reaches the server may create an account; each such account gets its own workspace.

<a id="license-required"></a>
## 402 `license_required`

Live sends, campaigns and automations, and the workspace (inbox, calendar, booking pages, drive) need a license key on a self-hosted server. Test API keys, Sandbox mode and the dashboard work without one. Add the key under **Settings → License**, or set `ONESEND_LICENSE_KEY` before you start the server. The response's `buyUrl` links to the pricing page. See [License key](https://onesend.email/docs/self-hosting/#license-key).

<a id="port-in-use"></a>
## A port is already in use (`EADDRINUSE`)

The server stops when its HTTP port (`PORT`, default 3000) is taken. The mail ports are optional: when SMTP (2587, 2525), IMAP (1143) or POP3 (1110) is taken, the server logs an error for that port and keeps running without it. Stop the other program, choose another port, or turn the port off with `0`: `ONESEND_SMTP_PORT`, `ONESEND_SMTP_IN_PORT`, `ONESEND_IMAP_PORT` and `ONESEND_POP3_PORT` (see [Ports for the workspace](https://onesend.email/docs/self-hosting/#ports-for-the-workspace)). `npm run doctor` shows which ports are free.

<a id="unauthorized"></a>
## 401 `unauthorized`, `invalid_api_key` or `invalid_session`

- `unauthorized`: the request has no `Authorization` header (or no session cookie). Send `Authorization: Bearer os_live_…`.
- `invalid_api_key`: the key is unknown or has been revoked. Keys are shown only once when created; if a key is lost, create a new one under **Developers → API keys** and revoke the old one.
- `invalid_session`: the session token (`oes_…`) or dashboard session has expired. Sign in again.

<a id="insufficient-scope"></a>
## 403 `insufficient_scope`, `session_required`, `test_mode`, `publishable_key` or `csrf_header_required`

- `insufficient_scope`: the key's permission does not cover the endpoint, for example a Read only key calling `POST /v1/emails`, or a Sending only key managing contacts. Create a key with the permission you need. Sending only sends, Read only reads, and Full access covers the whole data plane (sending, reading and content such as templates, contacts and campaigns). Configuration (sending providers, routing, domains, webhooks, workspace settings, the license, team and API keys) needs an Admin key (live) or a signed-in admin.
- `session_required`: managing API keys needs a signed-in session or a live Admin key. See [Authentication](https://onesend.email/docs/api/#authentication).
- `publishable_key`: Conversion tracking keys (`os_pub_…`) only work with `POST /t/conversion` from the `/t/onesend.js` script. Use a secret key for the API.
- `test_mode`: test keys (`os_test_…`) cannot change settings, webhooks, sending providers, routing, domains, mailboxes, suppressions, templates, campaigns, contacts, lists or segments, read the inbox, manage API keys or send campaigns. Use a live key. See [Authentication](https://onesend.email/docs/api/#authentication).
- `csrf_header_required`: a request authenticated with the dashboard cookie changed data without the `X-OneSend-Client: dashboard` header. Scripts should use a bearer token instead of the cookie.

<a id="validation-failed"></a>
## 400 `validation_failed`

`error.message` describes each field that failed in a sentence, for example "Recipient has too many addresses: at most 50 in one field, and 100 across to, cc and bcc." `error.details` has one entry per problem with `path`, `field`, `message` and `code`. A field the endpoint does not accept is reported as "Unknown field: …". Send JSON bodies with `Content-Type: application/json`.

<a id="no-broadcast-provider"></a>
## A campaign will not start: `no_broadcast_provider`

No active provider connection is allowed to send marketing email. Under **Sending providers**, open a provider whose terms permit marketing and turn on **Use for campaigns**.

## SMTP clients cannot authenticate

Without `ONESEND_SMTP_TLS_KEY` and `ONESEND_SMTP_TLS_CERT`, SMTP ingress does not offer STARTTLS. Clients that require STARTTLS then fail, and AUTH is accepted only from clients on the same host. Configure TLS as described in [SMTP](https://onesend.email/docs/smtp/#tls). On a trusted private network you can instead set `ONESEND_SMTP_ALLOW_INSECURE_AUTH=true`. The SMTP password must be an API key with Full access or Sending only; the username can be anything.

<a id="payload-too-large"></a>
## 413 `payload_too_large`, 415 `unsupported_media_type` or 429 `rate_limited`

- `payload_too_large`: the request body is over the limit for that endpoint (1 MB by default, 15 MB for sending with attachments, 50 MB for CSV imports). See [Request limits](https://onesend.email/docs/self-hosting/#request-limits).
- `unsupported_media_type`: the body was not sent with `Content-Type: application/json`. CSV imports also accept `multipart/form-data`.
- `rate_limited`: too many login, sign-up or browser conversion requests from one client. Wait for the time in the `Retry-After` header. Behind a reverse proxy, set `ONESEND_TRUST_PROXY=true` (or the number of proxies), otherwise every client shares the proxy's limit.

<a id="private-network"></a>
## A webhook, attachment URL or SMTP host on a private network is rejected

OneSend blocks requests to private, loopback and link-local addresses by default, to prevent server-side request forgery. Saving a webhook such as `http://localhost:…` returns 400 `unsafe_url`. If your webhook receiver, attachment host or self-hosted provider runs on your own network, set `ONESEND_ALLOW_PRIVATE_NETWORK=true`. For an SMTP relay on a private address, set `ONESEND_ALLOW_PRIVATE_SMTP=true`.

<a id="quota"></a>
## Emails stay `deferred` or `queued`

Every eligible provider has reached its daily or monthly limit, and the routing policy's fallback is `queue_until_reset`. The email is sent when a quota resets. Check **Dashboard** or `GET /v1/analytics/quota`, add a provider, or raise a connection's limit if the provider allows more. `POST /v1/route/preview` shows which providers are skipped and why.

Also check that the worker is running: `ONESEND_WORKER=off` disables it in that process.

<a id="mcp"></a>
## The MCP server returns 401

The MCP server needs a OneSend API key: `ONESEND_API_KEY` for stdio, or an `Authorization: Bearer` header from the client in HTTP mode. Check that `ONESEND_BASE_URL` points at your server. A 403 "Host not allowed" in HTTP mode means the request's `Host` header is not accepted; behind a reverse proxy, set `ONESEND_MCP_ALLOWED_HOSTS`. See [MCP](https://onesend.email/docs/mcp/).

## Getting more detail

- Set `LOG_LEVEL=debug` to log provider requests (credentials are redacted).
- With `NODE_ENV=production`, internal errors return "Something went wrong". The server log has the full error.
- `GET /healthz` reports whether the server and database are reachable.
