Skip to main content
Version: 9.10 (latest)

Troubleshooting

Solutions for common FiestaBoard issues, organized by what you're seeing.

Installation and Startup​

Settings or board credentials are gone after an update​

What you see: After running docker compose pull && docker compose up -d (or re-running the install commands), FiestaBoard comes up looking like a fresh install — your board API key is missing, plugins are disabled, and pages are gone. The container itself updated successfully.

Why it happens: The docker-compose.hub.yml and docker-compose.yml files use a relative bind mount for persistent data:

volumes:
  - ./data:/app/data

The ./data path is resolved relative to the directory you run docker compose from, not a fixed location. So if you originally ran docker compose up -d from ~/fiestaboard, your settings are saved in ~/fiestaboard/data. If you later run an update from ~ or ~/Downloads or any other folder, Docker creates a brand new empty data/ directory in that folder and mounts it instead — making FiestaBoard look like a fresh install. Your old data is not deleted; it's still sitting in the original folder.

Fix (recover your data):

  1. Stop the empty container:

    docker compose -f docker-compose.hub.yml down

  2. Find your original data folder. It's wherever you first ran docker compose up -d. Common locations to check:

    ls -la ~/data ~/fiestaboard/data ~/Downloads/data 2>/dev/null
    find ~ -maxdepth 4 -name 'config.json' -path '*/data/*' 2>/dev/null

  3. cd into the folder that contains the populated data/ directory (the one with config.json, pages.json, etc.).

  4. Make sure docker-compose.hub.yml lives in that same folder (download it again if needed), then start FiestaBoard from there:

    cd /path/to/your/original/folder
    docker compose -f docker-compose.hub.yml up -d

Prevent it next time: Always cd to the same folder before running any docker compose command. The simplest habit:

mkdir -p ~/fiestaboard && cd ~/fiestaboard
# ... all docker compose commands from here on out

If you want a setup that doesn't depend on which folder you're in, you can switch to a Docker named volume — but doing so requires migrating your existing data first. Open a discussion on GitHub if you'd like guidance.

Docker is not running​

What you see: Cannot connect to the Docker daemon

Fix: Make sure Docker Desktop is open and running.

  • Mac: Look for the whale icon in the menu bar at the top of the screen
  • Windows: Look for the whale icon in the system tray (bottom-right corner)
  • Linux: Run sudo systemctl start docker

Port already in use​

What you see: Bind for 0.0.0.0:4420 failed: port is already allocated

Fix: Something else is already using port 4420. You have two options:

  1. Find and stop it:

    # Mac/Linux
    lsof -i :4420

    # Windows
    netstat -ano | findstr 4420

  2. Use a different port by editing the ports line in your docker-compose.yml (or docker-compose.hub.yml):

    ports:
      - "9090:3000"   # Change 9090 to any free port

    Then access FiestaBoard at http://localhost:9090 instead.

Container won't start​

What you see: Container exits immediately or shows errors.

Fix: Check the logs for the actual error:

docker compose logs fiestaboard

Common causes:

  • Missing .env file (run cp env.example .env if you cloned the repo)
  • Docker doesn't have enough memory allocated (check Docker Desktop settings)
  • Corrupted build cache: try docker compose down && docker compose up -d --build

Build takes a long time on Raspberry Pi​

What you see: Build seems stuck during npm install or Python package installation.

Fix: This is normal. First builds on a Pi can take 10-20 minutes. To skip building entirely, use the pre-built image from Docker Hub:

docker compose -f docker-compose.hub.yml up -d

Board Connection​

Board not updating​

This is the most common issue. Work through this checklist:

  1. Is the display service running? Open http://localhost:4420 and check if the dashboard shows Running. If it shows Stopped or Disconnected, check that your Docker container is running (docker ps).

  2. Is your API key correct? Go to Settings in the web UI and verify your board API key.

  3. Is the API mode correct? Make sure you're using the right mode (Local API or Cloud API) for the key you entered.

  4. For Local API: Is your board on the same WiFi network as the computer running FiestaBoard?

  5. Check the logs for specific error messages:

    docker compose logs -f fiestaboard

401 Unauthorized from board API​

What you see: "401 Unauthorized" or "Invalid API key" errors in the logs.

Fix:

Board updates are slow or laggy​

Possible causes:

  • Cloud API mode has a 15-second rate limit between messages. This is normal.
  • High refresh interval - Check Settings to see how often FiestaBoard checks for updates
  • Network issues - For Local API, check your WiFi connection

Fix: If using Cloud API, set the refresh interval to at least 30 seconds in Settings. For Local API, try restarting FiestaBoard:

docker compose restart

Web UI Issues​

Web UI won't load at http://localhost:4420​

Checklist:

  1. Wait 30-60 seconds after starting - the server needs time to initialize
  2. Check if the container is running: docker ps
  3. Try the health endpoint: http://localhost:4420/api/health
  4. Check the logs: docker compose logs -f fiestaboard
Accessing from another device?

localhost only works on the machine running FiestaBoard. From other devices on the same network, use your server's IP address, for example http://192.168.1.50:4420. The FiestaPi image also provides http://fiestapi.local:4420; the default Docker bridge does not advertise fiestaboard.local.

I don't know my board's address​

Open fiestaboard.app/find on a phone or computer on the same Wi-Fi as the board and press Search my network. In Chrome or Edge, choose Allow when the browser asks about devices on your network. The page lists every FiestaBoard it finds; select yours to open it.

The search runs in your browser. Nothing about your network is sent anywhere.

If nothing is found:

  1. Make sure the device is on the same network as the board, not a guest network.
  2. Wait a minute or two after starting the board.
  3. Find the board in your router's list of connected devices and type its address into the box at the bottom of the page. If your network uses an uncommon range, type the range instead, for example 192.168.7.x.

Safari and Firefox do not let websites look for devices on your network. In those browsers the page offers the usual addresses to try instead.

Changes not saving​

Possible causes:

  • The data/ volume mount isn't working. Check your docker-compose.yml has:

    volumes:
      - ./data:/app/data

  • File permissions on the data/ directory. Try: chmod -R 755 data/

  • Container isn't running. Check with docker ps

Page previews look wrong​

Fix: The preview in the editor should match your board exactly. If it doesn't:

  • Make sure you're editing a page for the right device type (Flagship vs Note)
  • Check that template variables resolve correctly by looking at the live preview
  • Refresh the page in your browser

Plugin Issues​

Weather shows no data​

  1. Go to Integrations and check that the Weather plugin is enabled
  2. Click on the Weather plugin to check your API key is entered
  3. Verify you've entered a valid location
  4. Check if your API key is still active at WeatherAPI or OpenWeatherMap

Traffic plugin returns errors​

Common causes:

  • Google Routes API is not enabled in Google Cloud Console
  • Billing is not set up (required even for the free tier)
  • Invalid address format - try using coordinates instead of street addresses

See the Traffic Plugin guide for detailed setup.

Home Assistant connection refused​

  1. Is the Home Assistant URL correct and reachable from the computer running FiestaBoard?
  2. Is your long-lived access token still valid?
  3. If FiestaBoard runs in Docker and Home Assistant runs on the same machine, use your machine's local IP address (e.g., 192.168.1.100:8123) instead of localhost
  4. If the error names an address you didn't enter in the UI, a .env variable is overriding it. See A plugin ignores the settings saved in the UI.

A plugin ignores the settings saved in the UI​

A plugin variable set in .env (such as HOME_ASSISTANT_BASE_URL, WEATHER_LOCATION or STOCKS_SYMBOLS) wins over the value saved in the UI while it is set. The Integrations page still shows the saved value, so the two can disagree.

  1. Check the logs for a warning naming the variable: docker compose logs fiestaboard | grep "overrides the"
  2. Delete or comment out that line in .env.
  3. Recreate the container with docker compose up -d. A restart does not reload .env.

Values left unchanged from an old copy of env.example are ignored automatically.

A plugin shows stale or outdated data​

Plugins refresh their data at the interval set in Settings (default: 300 seconds). If data seems stuck:

  1. Try a Force Refresh from the API: curl -X POST http://localhost:4420/api/force-refresh
  2. Check plugin logs for errors: docker compose logs -f fiestaboard | grep plugin_name
  3. Verify the external API hasn't hit rate limits

Getting More Help​

Check the logs​

Logs are the best way to diagnose issues:

# See all recent logs
docker compose logs --tail=100 fiestaboard

# Follow logs in real time
docker compose logs -f fiestaboard

Interactive API documentation​

Visit http://localhost:4420/api/docs for the Swagger UI where you can test API endpoints directly and check service status.

Community support​

  • Discord - Ask questions and get help from other FiestaBoard users
  • GitHub Issues - Report bugs or request features

When reporting an issue, include:

  • What you expected vs. what happened
  • Steps to reproduce the problem
  • Relevant log output (docker compose logs fiestaboard)
  • Your environment (OS, Docker version, board model)