> ## Documentation Index > Fetch the complete documentation index at: https://dcc-5ccd5152.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Troubleshooting BigFred: Fix Common Server Problems > Diagnose and fix the most common BigFred problems: connection failures, locomotive not responding, slot exhaustion, session drops, and login issues. Most BigFred problems fall into a small number of categories: the server isn't reachable, a command station isn't communicating, sessions aren't persisting across restarts, or LocoNet's fixed slot table is full. Work through the accordion items below for step-by-step guidance on each. If you need more detail about logs and diagnostic tools, see [Diagnostics](/admin-guide/diagnostics). **Goal:** reach the BigFred web UI from your device. 1. **Confirm loco-server is running.** On the host machine, run: ```bash theme={null} supervisorctl status loco-server ``` The status should show `RUNNING`. If it shows `FATAL` or `STOPPED`, check the startup log: ```bash theme={null} supervisorctl tail loco-server stderr ``` 2. **Verify the server address and port.** By default BigFred listens on port **8080**. Open: ``` http://:8080 ``` Substitute your server's actual IP address. If you've changed the port in `loco-server.conf`, use that port instead. 3. **Check firewall and router rules.** Port 8080 must be reachable from your device. On a Linux host: ```bash theme={null} sudo ufw status # or sudo iptables -L -n | grep 8080 ``` Add an allow rule if the port is blocked. 4. **Test the health endpoint from another device** to confirm the server is up and the problem is network-side: ```bash theme={null} curl http://:8080/healthz # Expected: ok ``` If this returns `ok` but the browser can't load the UI, the issue is likely a browser extension, VPN, or mDNS hostname resolution problem. **Goal:** send speed and direction commands that actually move the locomotive. 1. **Check command station status.** Open **Admin → Command Stations** and confirm the station shows as online. An offline or error state means BigFred cannot reach the hardware. 2. **Check dcc-bus logs.** Open **Admin → Logs**, select the dcc-bus daemon for your command station, and look for connection errors or repeated retry messages. 3. **For Z21 command stations:** verify the Z21 IP address is correct and that UDP port **21105** is reachable from the BigFred server: ```bash theme={null} # Confirm UDP reachability (requires netcat with -u flag) nc -zu 21105 && echo "reachable" ``` Also confirm that the Z21's built-in firewall (if any) permits connections from the BigFred server IP. 4. **For LocoNet serial connections:** verify the device path and baud rate in your command station config. A common starting point if you're unsure of the device path is: ``` serial://autodetect:57600 ``` This lets BigFred scan for the first available serial port at 57600 baud. Set the explicit path once you've confirmed which device it maps to. 5. **Verify the DCC address.** The address configured in the BigFred vehicle roster must match the address programmed into the decoder. A mismatch results in commands going to a different (or non-existent) locomotive. 6. **Confirm the vehicle is in the layout roster.** Open the roster and check that the vehicle exists and is assigned to the correct layout. Vehicles not in the roster cannot be leased or driven. **Goal:** stay logged in after BigFred restarts. This is almost always caused by a missing `JWT_SECRET`. When no secret is configured, BigFred generates a random one on every startup. Any session token signed with the previous secret becomes invalid the moment the server restarts. **Fix:** set a stable, secret value in `loco-server.conf`: ```ini theme={null} JWT_SECRET= ``` Generate a strong secret with: ```bash theme={null} openssl rand -base64 32 ``` Restart loco-server after saving the change: ```bash theme={null} supervisorctl restart loco-server ``` From this point forward, all new sessions will remain valid across restarts as long as `JWT_SECRET` doesn't change. Do not share or commit your `JWT_SECRET` to version control. Anyone who obtains this value can forge valid session tokens. **Goal:** free up LocoNet slots so new locomotives can be activated. LocoNet command stations have a fixed slot table. BigFred reserves up to **80 slots** by default. When the table is full, no new locomotives can be activated until an existing slot is released. 1. Open **Admin → DCC Bus Slots** and select your LocoNet command station. 2. Check the **slot budget bar** at the top. If it reads `80 / 80` (or your configured maximum), the table is full. 3. Scan the lease table for **stale slots** — entries whose holder is no longer connected, or whose DCC address hasn't been driven in a long time. The **Last Drive** column and the amber row highlight help identify these. 4. Click **Release** next to each stale entry and confirm the dialog. 5. To prevent one user from monopolising the slot table in future, consider lowering the `MaxLoconetSlots` per-user cap in the command station configuration so slots are spread more evenly across operators. If you regularly hit slot exhaustion with a large roster, keep the slot diagnostics page open on a spare screen during operating sessions so you can catch and release stale entries before the table fills. **Goal:** pair a hardware or app-based throttle to BigFred. 1. **Confirm the protocol server is enabled.** Open **Admin → Command Stations**, select the relevant station, and verify that the Z21 or WiThrottle server is turned on. 2. **Check the expected ports:** | Protocol | Transport | Default Port | | ---------- | --------- | ------------ | | Z21 | UDP | 21105 | | WiThrottle | TCP | 12090 | Ensure your network firewall allows inbound connections on these ports to the BigFred server. 3. **For WiThrottle apps:** confirm the pairing sentinel address matches what the throttle app sees. The default sentinel address is **3**. If you've changed this in the command station config, enter the matching address in the app. 4. **Check dcc-bus logs for pairing errors.** Open **Admin → Logs** and select the dcc-bus daemon for the affected command station. Look for lines mentioning the handset's IP address, authentication failures, or "no free session" errors. 5. **Verify the handset is on the same network segment** as the BigFred server, or that routing is in place. Most throttle apps require multicast or direct IP access — they won't work across isolated VLANs without additional routing. **Goal:** see recent activity in the Audit Log. The audit log is backed by a Redis Stream in the Valkey sidecar. If Valkey is not running when BigFred starts, the audit service is disabled and the log will always appear empty — no error is shown to the user. 1. **Check Valkey logs.** Open **Admin → Logs** and select the Valkey log source. Look for startup errors or `FATAL` status. 2. **Check supervisord status** for the Valkey process: ```bash theme={null} supervisorctl status valkey ``` If it is stopped or in a crash loop, restart it: ```bash theme={null} supervisorctl start valkey ``` Then restart loco-server so it can reconnect to the now-running Valkey: ```bash theme={null} supervisorctl restart loco-server ``` 3. **Ensure you're running under supervisord.** If you started loco-server with `--no-supervisor`, the Valkey sidecar is not managed automatically. Remove that flag so supervisord starts and monitors all processes together. New audit entries only appear after loco-server successfully connects to Valkey. Past entries from before the outage are preserved in the Redis Stream and will reappear once the connection is restored. **Goal:** regain admin access when you can't log in. BigFred does not provide a PIN reset feature in the UI. The recovery path is to delete the database file (`bigfred.db`) so that loco-server re-seeds a fresh admin account on the next start. **This erases all data** — users, vehicles, layouts, and command station configuration. 1. Stop loco-server: ```bash theme={null} supervisorctl stop loco-server ``` 2. Delete the database file. The default file name is `bigfred.db` in the loco-server working directory; check your `loco-server.conf` for a custom `DB=` path: ```bash theme={null} rm /path/to/bigfred.db ``` 3. Start loco-server again: ```bash theme={null} supervisorctl start loco-server ``` 4. Log in with the default credentials: **admin / 123456**. 5. Change the PIN immediately from your account settings. Deleting `bigfred.db` permanently removes all users, vehicles, layouts, and command station configuration. Back up the file first if you want to preserve any of this data. **Goal:** prevent unintended emergency stops during an operating session. The dcc-bus dead-man safety feature applies an emergency stop to all active locomotives when the server stops receiving WebSocket heartbeat messages from the throttle client. The threshold is approximately **6 seconds** without a heartbeat. **Common causes:** * **WiFi drop** — the device running the BigFred throttle loses its connection briefly * **Browser tab backgrounded** — on mobile devices, switching away from the browser or locking the screen suspends the tab and halts the WebSocket * **Network congestion** — high latency causes heartbeats to arrive late **How to prevent it:** 1. **Keep the BigFred throttle tab active and visible.** On a phone or tablet, do not lock the screen or switch to another app while running locomotives. 2. **Prevent screen lock on your throttle device.** On Android: Settings → Display → Screen timeout → set to "Never" or a long interval while operating. On iOS: Settings → Display & Brightness → Auto-Lock → Never. 3. **Ensure a strong WiFi signal near the layout.** A dropped frame is all it takes to trigger the dead-man. Consider a dedicated access point close to the operating area if the signal is marginal. 4. **Use a wired connection for the BigFred server** rather than WiFi to eliminate one potential failure point in the path between the browser and the server. The dead-man brake is a safety feature, not a bug. It ensures that a disconnected phone doesn't leave a locomotive running unchecked on the layout. Design your operating setup so the throttle device stays connected and awake throughout the session.