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 command again

   docker build -t financial-dashboard ., then docker run -p 3030:3030 financial-dashboard.

A port is already in use

Bind for 0.0.0.0:3030 failed: port is already allocated
ports are not available: exposing port TCP 0.0.0.0:3030 … bind: address already in use
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 port 3030: often an earlier run of this dashboard, or another project's server.

1. 01

   Find what holds the port

   On macOS or Linux:

   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, or docker stop with the container's ID from docker ps. Then start the dashboard again.
3. 03

   Or use another port

   Keep the other program and start the dashboard on a free port, here 3041:

   How you run it	Command
   Docker	docker run -p 3041:3030 financial-dashboard
   Development server	yarn dev -p 3041
   Production build	yarn start -p 3041

   With Docker, change only the number on the left of -p: the app inside the container always listens on 3030.

   Expected result: The dashboard answers on localhost:3041Local.

The build fails

docker build stops with "failed to solve" and the step that failed; yarn build stops with the error itself. The usual causes:

• No connection or a timeout: the build downloads the dependencies, and the Inter and Noto Sans Arabic fonts from Google Fonts. A message such as "Failed to fetch Inter from Google Fonts." means the build could not reach them. Run the command again once you are online; with Docker, 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: build again without the cache.

docker build --no-cache -t financial-dashboard .

Without Docker, delete the node_modules and .next folders, then run yarn install and yarn build again.

Yarn says its version is 1.22

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

The project pins Yarn 4 through Corepack. This message means Corepack is not enabled yet, so an old global Yarn answered instead.

corepack enable

Then run yarn install again. Use Yarn rather than npm: yarn.lock is what keeps your install on the versions the template was tested with.

The corepack command is not found

corepack: command not found

Node.js 25 and newer no longer include Corepack. Install it once with npm, then turn it on:

npm install -g corepack
corepack enable

Then run yarn install again. The same two commands fix yarn: command not found.

Node.js is too old

You are using Node.js 18.20.4. For Next.js, Node.js version ">=20.9.0" is required.

Next.js 16 needs Node.js 20.9 or newer. Check your version with node -v. Install Node.js 22 or 24, open a new terminal, run corepack enable again, then yarn install and yarn dev.

With Docker this does not apply: the image brings its own Node.js 24.

The sign-in is refused

The email or password is incorrect.

The dashboard accepts one account only. Type its sign-in details exactly: the password is case sensitive. Check them in the installation guide.

"Please enter a valid email address" or "Password must be at least 6 characters" under a field means the form stopped before checking the account: fix that field first.

• The sign-in details

The dashboard sends me back to the sign-in page

Every page under /dashboard needs a signed-in user, and anyone else is sent to /login. The placeholder sign-in keeps you signed in in this browser only, so you sign in again in a private window, in another browser, after you clear the site's data, or after Logout in the user menu or Sign Out in the settings.

• How the sign-in works

A changed setting does nothing

NEXT_PUBLIC_DEMO_MODE and the other NEXT_PUBLIC_ values are compiled into the app when it is built. Changing one changes nothing until the app is built again.

• The settings

yarn start fails, or shows an old version

Could not find a production build in the '.next' directory. Try building your app with 'next build' before starting the production server.

yarn start serves the last production build, from the .next folder. Run yarn build first, and again after every change.

If the app shows errors that do not match your code, often after you changed a dependency's version or BUILD_STANDALONE, delete the .next folder and build again:

rm -rf .next
yarn build

On Windows, in PowerShell, delete it with Remove-Item -Recurse -Force .next.

The world map stays empty

The overview's world map downloads its country shapes from cdn.jsdelivr.net in the browser. Without an internet connection, or where a firewall blocks that address, the map shows no countries. The rest of the dashboard works offline.

• Serve the map yourself

A button does nothing, or saves nothing

That is how the template ships. It has no back end, so buttons that would ask a server for something are ready for your own code:

• Apple, Google, Remember me and Forgot password? on the sign-in page.
• Add Transaction, the quick transfer and the fast transfer: their forms open and check what you type, but nothing is stored.
• Add Card on the cards page, the header's search and refresh buttons, and Save Changes and Help & Support in the settings.

The transactions page's date range and Filter dialog do work: they narrow the table in the browser. It opens on the last 30 days, which holds every sample transaction.

• Sample data and your API

A new brand colour does not show

With demo mode on, the floating colour switcher saves the colour you pick in the browser, and that choice wins over the colour set in the code. Pick the same colour in the switcher, or clear the site's data for localhost:3030 in your browser. With demo mode off, the app always uses the colour set in the code.

• Colours and dark mode

The dashboard opens in Arabic

Opening / sends a visitor to /ar when the browser prefers Arabic, and to /en otherwise. Choose the other language in the header's language menu, or open /en/login directly.

• Languages

The folder looks different

Run the commands inside the folder the ZIP extracts to, dashboard-template-1. It holds Dockerfile, package.json, yarn.lock, messages, public and src. 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.