Docs / Reference / Troubleshooting
Troubleshooting
This guide lists the messages you are most likely to see, what they mean, what to do, and where to find the logs.
Updated 26 Oct 2026·Version 0.x
Early access. Requests are not retried for you, and nothing restarts unless you turned on automatic recovery. When an outcome is unknown, wait for it to settle instead of repeating the request.
1. Where to find logs
On the control plane host, the services run in Docker Compose. Run these in /var/lib/nile/compose:
cd /var/lib/nile/compose
sudo docker compose logs control-plane # the control plane
sudo docker compose logs web # HTTPS and the dashboard (Caddy)
sudo docker compose logs postgres # the database
sudo docker compose logs notifier # alert notifications
sudo docker compose logs idp # single sign-on, if installed
sudo /var/lib/nile/nile-install status # installation status
journalctl -u nile-gateway-firewall # gateway firewall service
sudo /var/lib/nile/nile-gateway-firewall –check
On each execution server, the agent and its helpers are systemd services, and each terminal is a Docker container:
journalctl -u fleet-agent # Fleet Agent
journalctl -u nile-watchdog # Watchdog, if installed
journalctl -u nile-vault # vault, if installed
curl -s http://127.0.0.1:8090/healthz | jq .control_plane
sudo fleet-agent ctl observe # what the agent reports
docker ps -a –filter label=nile.agent_id # the deployments’ containers
docker logs <container> # a terminal’s lifecycle log
Important. Before you share any log, remove anything that looks like a password, token, key or account login. PerkBridge hides credential-like values in its own logs, but check anyway.
2. Installing
| YOU SEE | WHAT TO DO |
|---|---|
| preflight refused: port 443 is in use | Stop the other web server on this machine, or use another server. |
| Docker is not installed: add –install-docker … | Add –install-docker to the install command, or install Docker yourself. |
| the Docker daemon is not reachable | Start Docker with sudo systemctl start docker and try again. |
| –idp-host must not be the dashboard’s host, on any port | Use a separate name such as id.example.com, or a second IP address. |
| Nile X is installed; this bundle is Y (upgrade is phase P4) | Upgrades are not available yet. Use the bundle of the installed version. |
| native mode is not in this release | Use –mode compose. |
| The control plane did not become healthy | Fix the cause shown in docker compose logs control-plane, then run the same install command again. It resumes. |
| Sign-in refused when the dashboard is not on port 443 | Set NILE_DASHBOARD_ORIGIN in /var/lib/nile/compose/.env. |
| Single sign-on fails right after a restart | The provider takes a few seconds longer to start. Try again shortly. |
More install messages are in Install the control plane.
3. Servers and agents
| YOU SEE | WHAT IT MEANS AND WHAT TO DO |
|---|---|
| Server setup: provisioning FAILED | The run stopped at the step shown on the server’s setup page, with the reason. Fix the cause (for example SSH access or sudo), then start a new run from the same page. Nothing is retried for you. |
| The server’s identity changed | The SSH host key differs from the one you trusted. Do not continue until you have checked the new fingerprint with your hosting provider. |
| The server’s agent is offline. Nothing can be sent until it reconnects. | Check the server is up and has outbound internet access. The agent reconnects by itself. The Agents page shows its last heartbeat. |
| The agent never connects after its address changed | Add the new address on the server’s Gateway access page. The control plane refuses agents from addresses it does not know. |
| Stale health | No report arrived in time (at least 90 seconds). Check the server and agent on the Servers and Agents pages. |
| VAULT_INSTALL_FAILED, VAULT_NOT_STARTED | nile-vault could not be installed or started during setup. Check journalctl -u nile-vault, then retry the run. |
| “Remember credentials on the server” is greyed out | The control plane has no vault key. See After the install. |
| Adding servers from the dashboard is not available | Add server works only on an install made from a development bundle until production-signed bundles are published. On an older installation, run install again with the new bundle. |
4. Deployments and credentials
| YOU SEE | WHAT IT MEANS AND WHAT TO DO |
|---|---|
| An operation is in progress … | Only one request per deployment runs at a time. Wait for it to finish. |
| Operation UNKNOWN or RECONCILING | The outcome could not be confirmed. Do not repeat the request. Wait for it to settle; if it does not, contact your administrator with the correlation ID. |
| Start is greyed out on a stopped deployment | A session runs once. Create a new deployment. |
| “Ask an administrator to install MetaTrader 5 on this server” | The platform is not on the server and you may not download images there. Ask for server:image_pull, or ask an administrator to choose Download under the server’s Runtime images. |
| STOPPED_BY_REBOOT | The server rebooted and nothing started the deployment again. Start it, or turn on remembered credentials with automatic use and Start again after a server reboot. See Outages and reboots. |
| AUTOMATIC_RESTART_LIMIT | Three automatic starts in an hour. Find the cause of the failures before you start it again. |
| SWITCH_FAILED, switch blocked | A failover switch could not finish, or an order of the old server is still unexplained. Trading stays halted for new positions until evidence settles it. See Failover. |
| That image is not approved for your organization. | Pick an approved image, or ask an administrator to approve one. |
| Delivery FAILED or EXPIRED | The single-use credential delivery did not reach the terminal in time, or was refused. Create a new deployment and enter the demo login again. |
| Broker authorization BROKER_AUTH_FAILED | The broker refused the login. Stop the deployment, check the demo login at your broker, and create a new deployment. |
| Broker authorization BROKER_UNDETERMINED | There was no evidence either way. Check in the terminal or at the broker; do not assume success. |
| Start blocked: encryption key not confirmed | Wait for the server’s new key to be confirmed, then start again. |
| 503 maintenance_backup | A backup is running. Try again shortly. |
| Broker: disconnected | Nothing is stopped because of it. MT5 reconnects by itself when it can. Deployments without credentials never connect. |
See Credentials for how delivery works.
5. Trading API refusals
A refused order returns 422 order_refused with a refused_reason.code. Nothing was sent to the broker. Programs must accept codes they do not know.
| CODE | WHAT TO DO |
|---|---|
| account_not_demo | Only demo accounts can trade. Use a broker demo account. |
| stops_not_supported | Stop loss and take profit are refused on MT5 market orders, or the broker does not accept them on the symbol. Send the market order without them, or use a limit or stop order. |
| order_type_not_supported, time_in_force_not_supported, broker_time_unknown | The broker does not accept this order type or time in force on the symbol, or the terminal has not reported the trade server’s time yet. |
| stops_invalid, price_invalid, expiration_invalid | A price or expiry is on the wrong side of the market, too close, or not a multiple of the tick size. |
| order_not_pending | The order you tried to modify or cancel no longer rests at the broker. |
| trading_disabled, route_disabled | Trading is turned off for the account or route. Turn it on if that is intended. |
| halted | An emergency halt is on. Closing positions still works. |
| account_not_ready, reconciliation_pending | The terminal, broker or bridge is not ready, or an earlier order is still being checked. Wait and try again. |
| quote_missing, quote_stale, spread_too_wide | No fresh price, or the spread is above the limit. Wait for the market. |
| volume_limit, exposure_limit, in_flight_limit, rate_limited | A risk limit refused the order. Check the account’s limits. |
| risk_rule_tripped | A risk rule tripped and may be latched. See Writing a rule. |
| risk_policy_pending | A saved policy revision is not applied on the server yet. Wait, then try again. |
| risk_outside_trading_hours, risk_market_closing, risk_news_window | A time rule blocks new positions now. Closes and cancels still work. See time rules. |
| risk_news_unavailable, risk_sessions_unavailable | A time rule cannot read the economic calendar or the symbol’s trading sessions, so it refuses rather than guess. Check the terminal’s connection. |
| risk_engine_unavailable | The risk engine on the server is not running or not ready. New orders are refused until it is back; closes still work. |
Full details are in the Trading API reference.
6. Notifications
| YOU SEE | WHAT TO DO |
|---|---|
| “External notifications are off” or “The notification secrets key cannot be used” | Run install again with your bundle, or restore the saved key and restart the control plane. |
| “not connected”, NOTIFIER_UNAVAILABLE | Check docker compose logs notifier and docker compose logs control-plane. |
| NOTIFICATION_CHANNEL_FAILING | Read the channel’s last result in the delivery log. |
See Alert notifications.
7. What to send to support
- the Request ID shown under an error message;
- the correlation ID of an operation, from the deployment’s Operations tab;
- the deployment ID and server ID, shown under their names;
- the agent version, from the Agents page;
- the time it happened, in UTC.
Never paste passwords, enrollment tokens, private keys or broker logins into a support request.
Was this page helpful?