Troubleshooting

The failures people hit most often with Nasnet Linux, from logins that will not stick to certificates that will not issue and subscriptions that come back empty.

Last updated Aug 17, 2026View as Markdown

Overview

Almost everything below comes down to one of three things: a .env value that is not what you think it is, HTTPS not being in place, or Xray-core not actually running. The panel logs the reason in every case, so start there:

docker compose logs -f app        # Compose install
journalctl -u nasnet-panel -f     # systemd install

Remember that changing .env does nothing until the panel restarts.

Signing in

The password is right and it still will not let me in. ADMIN_PASSWORD_HASH must be a bcrypt hash, not the password itself. Regenerate it, put the hash in .env, and restart:

htpasswd -nbBC 10 "" "your-password" | tr -d ':\n' | sed 's/$2y/$2a/'

Then confirm ADMIN_USERNAME matches what you are typing.

Login succeeds, then bounces me straight back to the login page. The session cookie is being dropped because it is a Secure cookie and you are on plain HTTP. Finish your TLS setup and set JWT_COOKIE_SECURE=true together with JWT_COOKIE_DOMAIN. On a test box using a bare IP, and only there, set JWT_COOKIE_SECURE=false and leave JWT_COOKIE_DOMAIN empty instead.

Certificates

ACME never issues a certificate. Work through these in order:

  • DNS for the domain in APP_BASE_URL must resolve to this server, and the ACME challenge has to reach it, so check for a firewall in front of port 80.
  • ACME_EMAIL must be set. Issuance is disabled without it.
  • The acme_data volume must be writable and must persist across restarts.
  • Set ACME_STAGING=true while you debug. Let’s Encrypt rate-limits failed attempts against the production endpoint, and you can lock yourself out for hours. Switch to production once a staging certificate issues cleanly.

Subscriptions

A subscription link returns nothing, or a client shows no servers. Check in this order:

  1. Is the subscription expired, or over its data limit?
  2. Is Xray-core running, and does it have inbounds configured? A link built from a core with no inbounds has no servers to hand back.
  3. Is APP_BASE_URL correct? It is the base for every /sub/{key} link, so a wrong value produces links that point somewhere that does not answer.

Telegram

The bot does not start. The panel logs the bot’s error and carries on running without it, so look in the panel logs rather than assuming the whole service failed. Then check that TELEGRAM_ENABLED=true and that TELEGRAM_BOT_TOKEN is correct. If the server cannot reach the Telegram API directly, set the TELEGRAM_PROXY_* SOCKS5 variables. In webhook mode, WEBHOOK_URL has to be a publicly reachable HTTPS URL.

Monitoring

The metrics endpoint returns nothing. METRICS_ENABLED must be true at startup, and the Metrics Enabled toggle under Settings → Server must be on, because the runtime toggle can disable collection even when the environment variable is set. If you configured METRICS_USERNAME and METRICS_PASSWORD, your scraper has to send basic auth.

Database

Migration errors on startup. Migrations run automatically on boot and the logs name the step that failed. For PostgreSQL, verify the DB_* connection settings and that the database is reachable and healthy. If a migration has left the database in a bad state, restore from a backup, and please report it, because that is a bug worth fixing.