Troubleshooting
Find the message you see on this page (your browser's find, Ctrl/Cmd + F, works well). Every command runs on the server, in the NuRoute install folder.
First steps for any problem
docker compose ps # every service should say "running" (migrate: "exited (0)")
docker compose logs --tail 50 api-gateway auth-service
A service that keeps restarting shows restarting in the first command; its logs usually say
why. Most problems are network access (see Requirements) or a
changed .env.
Getting help: the support bundle
./support-bundle.sh
It collects versions, service status and recent logs into one file, with secrets, keys and
message content removed, and prints its name (support-bundle-<date>.tar.gz). Look through it
(tar -tzf <file> lists what is inside), then email it to support@nuroute.ai with what you
were doing. Nothing is sent automatically.
Installer and script messages
Messages start with Error:. Grouped by the script that prints them.
One-line install (get.sh)
| Message | What to do |
|---|---|
curl is not installed / tar is not installed | Install them: sudo apt-get install -y curl tar (Ubuntu/Debian) or sudo dnf install -y curl tar |
could not reach github.com to find the latest NuRoute release | The server cannot reach github.com over HTTPS. Check its internet access or proxy, or name the release: NUROUTE_KIT_VERSION=1.0.0 before bash |
could not tell the latest NuRoute release from … | Name the release yourself with NUROUTE_KIT_VERSION=1.0.0 |
could not download release X of NuRoute-ai/nuroute-selfhosted | Check the version exists on the releases page and that the server can reach github.com |
nuroute already has NuRoute in it: cd nuroute and run ./install.sh … | NuRoute is already installed there. Run ./install.sh in that folder, or ./upgrade.sh <version> for a newer release |
install.sh
| Message | What to do |
|---|---|
Docker is not installed… | Install Docker: see Requirements |
Docker Compose is missing (the 'docker compose' command, v2 or newer)… | Install the Compose plugin: sudo apt-get install -y docker-compose-plugin, or reinstall Docker with its official script |
openssl is not installed (it generates your secrets)… | sudo apt-get install -y openssl |
Docker is installed but not running, or this user may not use it… | Start it (sudo systemctl start docker) or add your user to the docker group (sudo usermod -aG docker $USER, then log out and in) |
this server is smaller than NuRoute needs: … | Use a larger server (see Requirements), or add --force to try anyway (evaluation only) |
! Smaller than recommended: … Continuing because of --force. | A warning, not an error. Expect slowness under load |
set the domain: ./install.sh --domain nuroute.yourcompany.com | The installer could not ask for the domain (no terminal). Pass it with --domain |
a domain is required | Enter the domain when asked, e.g. nuroute.acme.com |
The database setup step failed. See: docker compose logs migrate | Run that command. Usually the database could not start: check free disk (df -h) and docker compose logs postgres |
NuRoute did not become ready in time… followed by NuRoute did not start. Nothing is lost: fix the cause and run ./install.sh again. | Run docker compose ps to find the service that is not running, then its logs. On a slow first start, waiting a few minutes and running ./install.sh again is often enough |
run this from the NuRoute install folder (the one with docker-compose.yml) | cd into the install folder first (any script) |
backup.sh and restore.sh
| Message | What to do |
|---|---|
no .env here: nothing to back up | You are not in the install folder, or NuRoute was never installed there |
the database is not running (docker compose start postgres) | Run that command, then back up again |
the dump in backups/… is damaged; nothing was replaced | The disk may be full or failing: check df -h, then back up again |
usage: ./restore.sh backups/<date-time> (a folder made by ./backup.sh) | Name a backup folder: ls backups/ lists them |
cancelled | You did not type restore at the question; nothing changed |
! Restored .env from the backup (its encryption keys differ from the current ones) | Not an error: the backup needed its own keys. Your old .env is replaced, so keep the backup's copy safe |
NuRoute did not start after the restore. See: docker compose logs | Check docker compose ps and the logs, or send a support bundle |
upgrade.sh
| Message | What to do |
|---|---|
usage: ./upgrade.sh <version>, for example ./upgrade.sh 1.1.0 | Give the version number from the release notes, without a v |
could not download X (check the version and this server's internet access). Nothing was changed. | Check the version exists on the releases page, and that the server can reach ghcr.io |
… is not on this server (load it with docker load first). Nothing was changed. | With --no-pull, every image of the release must be loaded first: docker load -i <file> |
! X did not start. Putting Y and the backup back… then the upgrade to X was rolled back; you are on Y again. Send upgrade-failure-X.log to support@nuroute.ai. | You are safely back on the previous version. Email us that log file |
reset-password.sh
| Message | What to do |
|---|---|
usage: ./reset-password.sh <email of the account> | Give the person's email address |
NuRoute is not running (docker compose up -d) | Start NuRoute first |
No NuRoute account with a password uses … | Check the address on the Members page. Accounts that sign in with Google have no password to reset |
Setup screen errors
| Message | What to do |
|---|---|
| "This licence key is not valid." | Copy the key again from your contract email; it starts with nrl_ |
| "This licence is already used by another install. Contact NuRoute to move it." | A key works on one install. Ask support@nuroute.ai to release it |
| "This licence has been revoked. Contact NuRoute." / "This licence has ended. Contact NuRoute to renew." | Contact NuRoute |
| "The NuRoute licence server could not be reached. Check this server can reach license.nuroute.ai over HTTPS." | Allow outgoing HTTPS to license.nuroute.ai (firewall, proxy), then try again |
| "Use your work email address. Personal email providers cannot start a trial." | Use your company address |
| "Your company has already used its trial. Contact us to continue." | One trial per company domain: contact sales@nuroute.ai |
| "Enter a valid email address." | Check the address for typos |
| "We could not send the email. Please try again in a moment." | Try again in a minute; if it persists, contact support@nuroute.ai |
| "That code is not right. Check the email and try again." | Use the newest code; codes from earlier attempts stop working |
| "This code has expired. Request a new one." | Codes last 30 minutes: select Send a new code |
| "Too many wrong codes. Start the trial sign-up again." | Start again with No key yet? Start a 14-day trial |
| "This trial sign-up was not found. Start again." | Start the trial sign-up again |
| "This trial has already been activated." | The trial is active: reload the page |
| "This NuRoute install already has its organization. Ask one of its admins to invite you." (at sign-up) | Sign-up closes after the first admin. Ask an admin to invite you from Members |
API errors
Status and type | Meaning | What to do |
|---|---|---|
402 licence_required | The install is not activated | An admin activates it on the setup screen |
402 licence_expired | The licence ended or could not be renewed for 5 days | See Licence & system and Licence and updates |
402 trial_ended | The trial is over | Contact NuRoute for a licence key |
503 licence_unavailable | The licence status could not be checked for a moment | Retry; if it persists, check docker compose ps (auth-service) |
401 | Missing or wrong API key | Check the Authorization: Bearer … header and the key on API Keys |
provider_error with the provider's message | The provider refused the request, e.g. a wrong or exhausted provider key | Check that provider's key and account on Model Catalog |
HTTPS certificate problems
The browser warns about the certificate, or Caddy's logs (docker compose logs caddy) mention
obtaining certificate errors:
- The domain's DNS must point at this server:
nslookup <domain>from outside. - Ports 80 and 443 must be reachable from the internet for the certificate to be issued (check your cloud provider's security group or firewall).
- Then restart Caddy:
docker compose restart caddy.
Behind your own proxy, Caddy obtains no certificate; see Behind your own HTTPS proxy.
Port 80 or 443 already in use
docker compose up fails with bind: address already in use: another web server (often nginx
or Apache) uses the port. Stop it (sudo systemctl disable --now nginx), or run NuRoute behind
it as described in Behind your own HTTPS proxy.