Troubleshooting

Docker is not running

failed to connect to the docker API at unix:///…/docker.sock; check if the path is correct and if the daemon is running

Older Docker versions say "Cannot connect to the Docker daemon" instead. Either way, the Docker engine is not started.

1. 01

   Open Docker Desktop

   Start Docker Desktop and wait until it reports that the engine is running. On Linux, start the service: sudo systemctl start docker.
2. 02

   Check that Docker answers

   TerminalCopy

   docker info

   Expected result: It prints a Server section instead of an error.
3. 03

   Run your start command again

   docker compose up --build for the Full Stack, or your docker build and docker run for the Admin Dashboard package.

A port is already in use

ports are not available: exposing port TCP 0.0.0.0:3030 … bind: address already in use
Bind for 0.0.0.0:3030 failed: port is already allocated
Error: listen EADDRINUSE: address already in use :::3030

The first two lines come from Docker, the last from yarn dev or yarn start. Another program already listens on 3030 or 8000: often an earlier run of the dashboard, or another project's dev server.

1. 01

   Find what holds the port

   On macOS or Linux, with the port from the message:

   TerminalCopy

   lsof -i :3030

   On Windows, in PowerShell:

   TerminalCopy

   netstat -ano | findstr :3030
2. 02

   Stop it

   Close that program, or stop the earlier run: Ctrl+C in its terminal, docker compose down in its folder, or docker stop for a container you started with docker run. Then start the dashboard again.
3. 03

   Or run the dashboard on other ports

   With the Full Stack in Docker, create a file named .env in the dashboard-2-full-stack folder, beside docker-compose.yml, with the port you need. DASHBOARD_PORT moves the dashboard and API_PORT the API; the addresses the apps use, CORS_ORIGIN included, follow by themselves.

   dashboard-2-full-stack/.envCopy

   DASHBOARD_PORT=3040

   Then run the same command again. A failed start picks up where it stopped:

   Terminalin dashboard-2-full-stackCopy

   docker compose up --build

   Expected result: The dashboard answers on its new port, here localhost:3040Local.

• Admin Dashboard package in Docker: change the number on the left of -p, for example docker run -p 3040:3030 dashboard-2, and open localhost:3040Local. The app inside the container always listens on 3030.
• Without Docker: set PORT=3040 in the dashboard's .env (create the file with just that line if you have none), or run PORT=3040 yarn dev on macOS and Linux. With an API, add the new address to the API's CORS_ORIGIN and FRONTEND_URL too.
• The API without Docker: change PORT in back-end/.env, and NEXT_PUBLIC_API_BASE_URL and NEXT_PUBLIC_WEBSOCKET_BASE_URL in the dashboard's .env, together.

The Docker build fails

The first build downloads the base images, every dependency and the dashboard's Arabic font from Google Fonts, then builds the images. It stops with "failed to solve" and the step that failed when something gets in the way.

• No connection or a timeout: the build needs internet access. Run the command again once you are online; finished steps are cached.
• No space left on device: free space in Docker Desktop, or check what Docker uses with docker system df.
• It fails at the same step every time: rebuild without the cache, then start.

docker compose build --no-cache
docker compose up

For the Admin Dashboard package, add --no-cache to your docker build command.

A first start that seems stuck is usually still seeding the sample data. The dashboard starts only once the API reports itself healthy, which can take up to a minute.

Yarn says its version is 1.22

This project's package.json defines "packageManager": "yarn@4.8.1…". However the current global version of Yarn is 1.22…

Each app pins Yarn 4 through Corepack. This message means Corepack is not enabled yet, so the old global Yarn answered instead.

corepack enable

Then run yarn install again. If your Node.js has no Corepack (Node.js 25 and newer), install it first with npm install -g corepack.

The dashboard does not start on an older Node.js

node: bad option: --env-file-if-exists=.env

The dashboard's yarn dev and yarn start read .env with an option Node.js added in version 22.9. Check yours:

node -v

If it prints a version below 22.9, install Node.js 22.9 or newer, run corepack enable again, delete the app's node_modules folder and run yarn install again. With Docker none of this applies: the images bring their own Node.js.

The API stops before starting

The API cannot start: JWT_SECRET is not set. Set it in back-end/.env to the output of: …
The API cannot start: JWT_SECRET is still the example value from .env.example, so anyone can sign a token for any account. …
The API cannot start: CORS_ORIGIN is not set. List the dashboard origin (comma separated if there are several), …

The API checks its settings before it starts and prints one line per problem. The causes:

• There is no `.env` file, or `JWT_SECRET` is empty. Create the file in back-end with cp .env.example .env.
• `JWT_SECRET` is still the example value with `NODE_ENV=production`. Anyone could sign a token with the public example, so a production start refuses it. Generate your own secret.
• `CORS_ORIGIN` is empty with `NODE_ENV=production`. Set it to the dashboard's address.

Generate a secret with:

node -e "console.log(require('crypto').randomBytes(48).toString('hex'))"

With Docker you do not need one: a container without a JWT_SECRET of its own, or with the example one, generates a secret and keeps it in the data volume.

• API settings

Sign-in fails

• Check the account. The Super Admin is admin@example.com with Admin@123; the other sample admins use admin123.
• "That email and password combination didn't work. Please try again." answers a wrong password and an unknown email alike, and also a database with no accounts. Without Docker, run yarn seed in back-end: yarn dev creates the tables by itself, but only the seed adds the accounts.
• "Too many failed sign-in attempts. Wait 15 minutes, then try again." One address failed RATE_LIMIT_LOGIN sign-ins (10 by default) within 15 minutes. Wait, or restart the API: the count is kept in its memory.
• The sign-in page never answers. The dashboard cannot reach the API: see the next problem.
• You changed the Super Admin's password and no longer have it: start over with fresh sample data, below.

Sign-in fails

• On the mock API, sign in with admin@example.com and Admin@123, or a sample Viewer such as john.smith@admin.com with admin123. These accounts live in your browser: a password you changed there stays changed until you clear the site's data.
• On your own API, the account has to exist there. On this template's API, the seed adds the same accounts. If no account works, the dashboard may not reach the API: see the next problem.

Pages stay empty and the browser reports CORS

Access to XMLHttpRequest at 'http://localhost:8000/api/auth/login' from origin 'http://localhost:3040' has been blocked by CORS policy

The browser's console shows this line when the dashboard runs on an address the API does not accept. The API answers browsers only from the addresses in CORS_ORIGIN, which defaults to http://localhost:3030.

CORS_ORIGIN=http://localhost:3040
FRONTEND_URL=http://localhost:3040

• Write each address exactly as the browser shows it, with the scheme and the port and without a trailing slash, comma separated if there are several. Then restart the API.
• FRONTEND_URL is the one address the live permission updates accept. Move it with the dashboard.
• With the Full Stack in Docker you do not edit these: DASHBOARD_PORT and DASHBOARD_URL in the .env beside docker-compose.yml set them.
• A dashboard that cannot reach the API at all, because it is stopped or at another address, fails the same way without the CORS line. Check that localhost:8000/api/healthLocal answers, and that the dashboard's NEXT_PUBLIC_API_BASE_URL names that API.

The dashboard shows sample data instead of my API

Sample data
No API is connected (NEXT_PUBLIC_API_BASE_URL is empty), so the dashboard runs on built-in sample data. …

The dashboard was built without an API address, so it runs on its built-in mock API. That happens without a .env file, with NEXT_PUBLIC_API_BASE_URL= empty, or with a Docker image built without the --build-arg.

• Without Docker: cp .env.example .env in the dashboard's folder, check NEXT_PUBLIC_API_BASE_URL, then restart yarn dev, or run yarn build again for a production build.
• Docker, Admin Dashboard package: build the image again with --build-arg NEXT_PUBLIC_API_BASE_URL=…, as in the installation guide.
• Docker Compose: the compose file always builds the dashboard with the API's address, so this notice does not appear there.

• The built-in mock API

A change to the dashboard's .env does nothing

Every NEXT_PUBLIC_* value is compiled into the JavaScript the browser loads when the app is built. Changing the file changes nothing until the app is built again.

A role change reaches the dashboard only after a reload

When a role's permissions change, the API tells every signed-in admin's dashboard over a WebSocket, and the menus and buttons follow without a reload. The dashboard connects to NEXT_PUBLIC_WEBSOCKET_BASE_URL, the API's address without /api, and the API accepts the connection only from FRONTEND_URL, the dashboard's own address.

• Set both to where the apps really run, then restart the API and rebuild the dashboard.
• An unset FRONTEND_URL accepts only http://localhost:3030.
• The dashboard also reads the permissions again on every page it opens, so nothing stays out of date for long.

The AI assistant asks for an API key

The server has no key for this model's provider. Add your own API key to keep going.

The API has no key for the provider of the model you picked. Either paste your own key in the dialog, which stays in your browser, or add the provider's key to back-end/.env and restart the API (with Docker Compose, docker compose up again).

gemini-3.6-flash has no requests left on this API key right now. Pick a different model from the list above the chat, or try again in a few minutes.

The provider refused the request because the key's quota is used up, which is common on a free key. Pick another model in the picker, or try again later.

• The AI assistant

A picture cannot be uploaded

Image uploads are not set up on this server yet. Add the Cloudflare R2 settings to the API environment to turn them on.

Profile pictures and the assistant's image attachments are stored in a Cloudflare R2 bucket. Set the five R2_* variables in back-end/.env and restart the API. Everything else works without them.

• Image uploads

The greeting shows no weather

The weather in the overview's greeting needs a WeatherAPI.com key in WEATHER_API_KEY, read by the dashboard's own server. Without it the greeting shows without the weather and nothing else changes.

• Without Docker, in the dashboard's .env, then restart.
• With Docker Compose, in the .env beside docker-compose.yml, then docker compose up again.
• With the dashboard's image, on docker run: -e WEATHER_API_KEY=....

MySQL refuses to start or to seed

The API creates its tables in a database that already exists; it does not create the database itself. Create an empty database first, give its name to DB_DATABASE in back-end/.env, then run yarn seed.

• Check the five DB_* connection values and that DB_TYPE=mysql.
• With NODE_ENV=production the running API never creates tables, so yarn seed:prod has to run once after yarn build, before the first start.
• The Docker image creates the database by itself only on SQLite. On MySQL, run node dist/database/seeder.js once in the container yourself.

• Use MySQL instead of SQLite

The API container cannot find its entrypoint

exec /usr/local/bin/docker-entrypoint.sh: no such file or directory

The script has Windows line endings, which an editor or Git on Windows can add. The shipped API Dockerfile strips them while it builds, so this appears only with an image built from a changed Dockerfile. Keep its sed -i 's/\r$//' line, or save the script with LF line endings, then rebuild without the cache.

The folder looks different

Run the commands inside the folder the ZIP extracts to. If the unzip command is missing, extract it with your file manager instead; some tools add an extra folder named after the ZIP, so move into the inner one.

Start over with fresh sample data

With the Full Stack in Docker, from the dashboard-2-full-stack folder:

docker compose down -v
docker compose up

Without Docker, stop the API, then in back-end:

rm -f database.sqlite* && yarn seed

In PowerShell:

Remove-Item database.sqlite*; yarn seed

Reset the sample data on the mock API

On the built-in mock API, the sample data and everything you changed live in your browser. Clear the site's data for the dashboard's address in your browser's settings and reload: the samples come back as they shipped.