Skip to main content
DEJA.jsDEJA.js
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.dejajs.com | bash

Firebase Connection Errors

Symptoms: Logs show Firebase or Firestore errors. The Throttle and Cloud apps 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.dejajs.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 port, change it: VITE_WS_PORT (WebSocket, default 8082) or WITHROTTLE_PORT (WiThrottle, default 12090) in ~/.deja/.env, or via the /settings panel for the WebSocket port. Restart after changing.

MQTT Broker Not Available

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

  1. Confirm a broker is running (e.g. Mosquitto) at the address in MQTT_BROKER (default mqtt://localhost:1883).
  2. Check for a port conflict — if something else is already using port 1883, the broker itself may have failed to start.
  3. Not using MQTT/IO devices? Set ENABLE_MQTT=false in ~/.deja/.env (or toggle it off via the /settings panel) to silence the retries.

The server keeps retrying with backoff rather than crashing, so this is safe to ignore if you don't have IO devices connected.

Subscription Issues

"Subscription inactive"

Your subscription status is one of canceled, unpaid, incomplete, or incomplete_expired — Visit dejajs.com to check your account status and renew. Note that a past_due status (e.g. a failed card charge) does not block the server — it's still treated as active while billing retries.

The server allows a 48-hour grace period when it can't reach the internet — if your subscription was active within the last 48 hours, the server will continue running using its cached status.

"Cannot verify subscription"

The server needs to verify your subscription online periodically. If it can't reach Firebase and the cached verification is older than 48 hours, it will stop.

Connect the computer to the internet and restart the server: deja restart.

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.js community for help from other users.