Skip to main content
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.
Goal: reach the BigFred web UI from your device.
  1. Confirm loco-server is running. On the host machine, run:
    The status should show RUNNING. If it shows FATAL or STOPPED, check the startup log:
  2. Verify the server address and port. By default BigFred listens on port 8080. Open:
    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:
    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:
    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:
    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:
    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:
Generate a strong secret with:
Restart loco-server after saving the change:
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: 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:
    If it is stopped or in a crash loop, restart it:
    Then restart loco-server so it can reconnect to the now-running Valkey:
  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:
  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:
  3. Start loco-server again:
  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.