Troubleshooting

Invalid environment configuration

Auvyra lists the variables at fault. Run pnpm env:generate if you have no .env, or check each named variable against Environment Variables.

"Unknown DATABASE_PROVIDER"

DATABASE_PROVIDER names an engine without an adapter. Use mongodb, postgresql, mysql, mariadb or sqlite.

Could not connect to MongoDB

• Check the server is running: docker compose ps
• Check DATABASE_URL, including the database name and percent-encoded password
• For hosted MongoDB, allow your server's IP address

Could not connect to PostgreSQL

• Check the server is running and the database exists
• Check DATABASE_URL, including the percent-encoded password
• The error includes a code: ECONNREFUSED means nothing is listening, and 28P01 means a wrong password

Could not connect to MySQL or MariaDB

• Check the server is running and the database exists
• Check DATABASE_URL, including the percent-encoded password
• The error includes a code: ECONNREFUSED means nothing is listening, and ER_ACCESS_DENIED_ERROR means a wrong password

Could not open the SQLite database

• Check DATABASE_URL is a full path, starting file:/
• Check Auvyra can write to that folder
• In Docker, use a path under /data, because everything else in the container is read-only

Docker reports a required variable is missing

Compose needs .env in the repository root. Run node scripts/generate-env.mjs. If you already have a .env, this adds the passwords it lacks and changes nothing else.

Emails are not arriving

• Open Integrations and select Send a test email to me, which reports the reason. A mail server on your own network with a self-signed certificate is not accepted, so use None only if it is private
• If the test works but your subscribers see nothing, check your spam folder and your domain's SPF and DKIM records
• A new subscriber is not sent anything until they confirm their address
• Links in emails point at the wrong place: check APP_URL

I am signed out immediately after logging in

If APP_URL starts with https:// but you are visiting over plain http://, the browser discards the secure session cookie. Make APP_URL match the address you use.

The setup token is rejected

Copy SETUP_TOKEN from .env exactly. If you changed it while Auvyra was running, restart Auvyra.

AzuraCast says "private or reserved network"

Auvyra blocks private addresses by default so that a saved URL cannot be used to probe your internal network. If AzuraCast really is on your network, set AZURACAST_ALLOW_PRIVATE_NETWORKS=true and restart.

AzuraCast says it is rate limiting requests

Your AzuraCast server is limiting how often it can be called. Wait a minute and try again.

AzuraCast: "Could not reach that AzuraCast server"

Check the address from the Auvyra server, not your own computer. In Docker, localhost means the container.

Is Auvyra healthy?

GET /api/health returns 200 with {"status":"ok"} when the database is reachable, and 503 otherwise.