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

Source: https://joinnasnet.com/en/guides/nasnet-linux/troubleshooting/
Last updated: 2026-08-17

---

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

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

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

## Related

- [Backup and restore](/en/guides/nasnet-linux/backup/)
- [TLS and domains](/en/guides/nasnet-linux/tls-and-domains/)
- [Getting support](/en/guides/nasnet-linux/support/)