Skip to main content
DEJA
Sign up

Troubleshooting

If something isn't working right, start here. These are the most common issues and their fixes. For all of these, running deja logs is a great first step — it shows you exactly what the server is doing (or what went wrong).

Server Not Connecting to EX-CommandStation

Symptoms: deja status shows no serial port, or the Throttle app says "Disconnected."

  1. Check the USB cable — make sure it's plugged in at both ends. Try a different USB port on the computer.
  2. Run deja status — look under Connections for a serial port like /dev/ttyUSB0 or /dev/tty.usbmodem*. If none is listed, the server can't see the EX-CommandStation.
  3. Restart the server — deja restart will re-scan for serial ports and try to connect again.
  4. Try unplugging and replugging the USB cable, then restart the server.

Serial Port Permission Denied (Linux / Raspberry Pi)

Symptoms: The server starts but can't open the serial port. Logs show a "permission denied" error.

Run this command once to add your user to the dialout group:

sudo usermod -a -G dialout $USER

Then log out and log back in (or reboot). This only needs to be done once — after that, the server will always have access.

Server Won't Start

Symptoms: deja start shows an error or the server exits immediately.

  1. Check Node.js version: Run node --version — you need v20 or later. If you need to upgrade, visit nodejs.org.
  2. Check the logs: Run deja logs to see what error the server reported.
  3. Reinstall: Run the installer again — it downloads a fresh copy and reconfigures:
    curl -fsSL https://install.dejadcc.com | bash

Firebase Connection Errors

Symptoms: Logs show Firebase or Firestore errors. Throttle can't see the server.

Your Firebase credentials may be missing or incorrect. They live in ~/.deja/.env (see Configuration).

  1. Run deja logs and check for the specific Firebase error — it usually names the missing or invalid credential.
  2. Re-run the installer to fetch a fresh, correctly configured .env:
    curl -fsSL https://install.dejadcc.com | bash
  3. If you've hand-edited ~/.deja/.env, double-check the VITE_FIREBASE_* values against a clean install, then restart: deja restart.

No Layout Configured

Symptoms: The server exits immediately on startup with a "No layout configured" message telling you to run deja login.

The server refuses to start without a layout, on purpose — attaching to the wrong layout is treated as a hazard, not a warning. Run:

deja login

This links the server to your account and layout and writes layoutId to ~/.deja/config.json. Alternatively, set LAYOUT_ID directly in ~/.deja/.env.

Port Already In Use

Symptoms: Logs show Port <number> is already in use — is another server instance running? for the WebSocket server ([WS]) or the WiThrottle server ([WITHROTTLE]).

  1. Check for a duplicate server instance: Run deja status — if a server is already running, use that one instead of starting a second.
  2. Stop the existing process: deja stop, then deja start again.
  3. If another application owns the WebSocket port, change it: VITE_WS_PORT (default 8082) in ~/.deja/.env, or with deja config, or settings in the console. Restart after changing.
  4. If another WiThrottle server owns port 12090 (JMRI with its WiThrottle server enabled, for example) — the port is fixed so throttle apps can always find it. Stop the other server, or turn DEJA's off with deja config set withrottle.enabled false.

MQTT Broker Not Available

Symptoms: Logs show [MQTT] Broker not available. Will retry with exponential backoff.

The server normally runs its own broker, so this only appears when it is using an external broker — check the startup line [MQTT] Using external broker — … for the reason:

  1. … is not this machine — MQTT_BROKER (or mqtt.broker in ~/.deja/config.json) points at another host. Make sure that broker is running, or set it back to mqtt://localhost (via deja config) to use the built-in one. A warning naming this machine's current LAN IP is logged when the address looks like a stale local one.
  2. … port 1883 already in use — another broker (e.g. Mosquitto) owns the port but isn't accepting connections. Stop it, or fix it.
  3. … embedded broker disabled — MQTT_EMBEDDED=false is set. Remove it to use the built-in broker.
  4. Not using IO devices at all? Set ENABLE_MQTT=false in ~/.deja/.env (or toggle it off with deja config, or settings in the console).

The server keeps retrying with backoff rather than crashing.

Server Went Into Standby (Loop)

Symptoms: trains stopped and track power went off right after you were actively using the layout, with no 60-second warning. deja status only shows standby for a background server (deja start -b); in the deja start console, the status bar shows 💤 STANDBY (loop).

This is the loop breaker, not the idle timer. It fires immediately (no warning) when it sees:

  • the same command repeat more than 30 times in 10 seconds, or
  • more than 20 commands per second arriving sustained for 10 seconds.

The log line names the source and the command that tripped it, e.g. 💤 Standby (loop) — throttles:3:40:true ×31 in 10s. Trains stopped, track power OFF.

Common cause: a fast feedback loop between apps or browser tabs can trip it — e.g. the same throttle open in several tabs, each echoing the other's speed/function update back and forth. A slower back-and-forth may not trip it; thresholds are still being tuned from real-world testing.

Throttle doesn't show standby yet — if a throttle stops responding, check the server console or run deja status.

Fix:

  1. Close the extra tabs (or duplicate app instances) sending the command.
  2. Wake the server: type resume or continue in the deja start console, or run deja resume for a background server (deja start -b).
  3. Track power stays off after resume — turn it back on from a throttle when you're ready.

Still stuck? Book a session with Track & Trestle

If you've worked through the steps above and the server still won't behave, Track & Trestle offers paid one-on-one sessions — see Support, or open Get help in Throttle. The community Discord is a good place to compare notes with other DEJA users.

[CONFIG] error at startup

The server couldn't read ~/.deja/config.json (it's missing or corrupt) and exited. Run deja login to relink this machine to your layout, then deja start.

deja Command Not Found

If the terminal says deja: command not found after installation:

  1. Open a new terminal window — the installer added deja to your PATH, but the current terminal may not have picked it up yet.
  2. Or reload your shell config:
    source ~/.zshrc    # if using zsh
source ~/.bashrc   # if using bash
  3. Or run it directly:
    ~/.deja/bin/deja status

Still Stuck?

If none of the above fixes your issue:

  1. Run deja logs -n 100 and look for error messages near the bottom.
  2. Run deja status and note any warnings.
  3. Check the DEJA community for help from other users.