Troubleshooting
This page lists common symptoms, their probable cause and the action to take. It is limited to cases documented in NGX Ops behavior.
Installation and dashboard
| Symptom |
Cause |
Action |
| The CrowdSec page stays empty or "not available" |
The NGX Ops container cannot reach CrowdSec |
Connect the container to CrowdSec's Docker network (see CrowdSec) |
| Challenge statistics are empty |
The dashboard cannot reach the challenge container |
Put them on the same Docker network; the challenge image must be up to date |
| The first Git clone fails |
An interrupted temporary folder remains in the Git workspace |
NGX Ops cleans known folders; otherwise it names what remains, to delete manually |
| Online editing or local restoration is refused |
Git is configured: the repository is the source of truth |
Change the repository then deploy; git revert to go back |
challenge_* settings are not taken into account |
The Nginx configuration was not regenerated |
Use Regenerate and reload Nginx from the HTTP challenge page |
| Webhooks disappear after a restart |
They are only kept in memory |
Recreate them, see REST API and webhooks |
Backups
| Symptom |
Cause |
Action |
| S3 archives disappear |
Rotation deletes old .zip files in the prefix |
Use a dedicated prefix; adjust s3_keep |
Unreadable .ngxb archive |
Wrong passphrase or tampered archive |
Check the passphrase variable (HUB_, S3_ or BACKUP_); no recovery without it |
| Three copies at each change |
auto_local, auto_git and auto_s3 are all active |
Choose a single automatic destination |
Logging
| Symptom |
Cause |
Action |
| The log store refuses to start |
pseudonymized mode without LOGSTORE_PSEUDO_KEY, or LOGSTORE_REQUIRE_TIMESCALE=true without TimescaleDB |
Provide the key (32 characters minimum) or a TimescaleDB database |
| The shipper no longer sends |
write token refused, or log store unreachable |
See the shipper's GET /status; access logs are caught up on return, the buffer is capped |
| Access lines are missing after a rotation |
Rotation by renaming to a name outside the pattern |
Use copytruncate, or a name that matches the pattern |
| Decisions are missing |
The shipper was stopped: they are not replayed |
Accepted behavior; keep the shipper started |
| A statistic times out |
Period too long on a large volume (15 s timeout) |
Reduce the period, see Log store capacity |
Hub
| Symptom |
Cause |
Action |
| Instance "Offline" |
3 consecutive collection failures |
Check the HTTPS URL, the certificate, HUB_TOKEN_SHA256 on the dashboard side |
| Instance refused on a private network |
Protection against requests to internal destinations |
Set security.allow_private_networks or allowed_cidrs |
| Tokens and MFA unreadable after a restore |
HUB_SECRET_KEY lost or different |
Restore the original key along with /data |
admin password lost |
— |
docker compose exec hub node bin/hub-admin.js set-password admin --must-change |
| The archive does not open in the browser |
HTTPS (or localhost) required, or wrong passphrase |
Switch to HTTPS; use ngxb-decrypt.js as a fallback |
Remote agents
| Symptom |
Cause |
Action |
| The agent does not start |
--relay-*-advertise is a bare port number |
Give the full address, for example http://10.0.5.9:8080 |
| 502 error in relay mode to an HTTPS service |
Self-signed certificate refused by the agent |
Enable RELAY_BACKEND_INSECURE_SKIP_VERIFY=true |
| The token is no longer displayed |
It is only shown once |
Regenerate the token from the Remote hosts page |
| WebSocket or SSE does not go through |
Tunnel mode: not supported |
Switch the vhost to relay mode |
To understand the state of a virtual host, the Diagnostics page tests its backends and shows its configuration. The state of each component is visible through Health and Redis.