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 a single app.

A port is already in use

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

The first two lines come from Docker, the last from yarn dev. Another program already listens on 3030, 3031 or 8000: often an earlier run of the agency, 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 :3031

   On Windows, in PowerShell:

   TerminalCopy

   netstat -ano | findstr :3031
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 agency again.
3. 03

   Or run the agency on other ports

   With the full stack in Docker, create a file named .env in the velra-real-estate-full-stack folder, beside docker-compose.yml, with the port you need. SITE_PORT moves the website, ADMIN_PORT the dashboard and API_PORT the API; the addresses the apps use, CORS_ORIGIN included, follow by themselves.

   velra-real-estate-full-stack/.envCopy

   ADMIN_PORT=3041

   Then run the same command again. A failed start picks up where it stopped. Docker names one busy port at a time: if it stops on another one, add that one to .env as well.

   Terminalin velra-real-estate-full-stackCopy

   docker compose up --build

   Expected result: The app answers on its new port, here localhost:3041Local.

The Docker build fails

The first build downloads the base images and every dependency, 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.
• Compose rejects `docker-compose.yml` itself, naming `env_file`: your Compose is older than 2.24. Update Docker Desktop, or the Compose plugin on Linux.

docker compose build --no-cache
docker compose up

For a single-app package, add --no-cache to your docker build command.

A first start that seems stuck is usually still seeding the demo agency. The website and the dashboard start only once the API reports itself healthy.

Yarn says its version is 1.22

This project's package.json defines "packageManager": "yarn@4…". 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 leave it out), install it first with npm install -g corepack. npm and pnpm are not used: each app ships its own yarn.lock.

An install or a start fails on an older Node.js

Every app declares Node.js 22 or newer, and the Docker images run on Node.js 24. An older Node.js shows up as an install that fails to build a package, or an app that stops at start.

node -v

If it prints a version below 22, install Node.js 22 or newer, run corepack enable again (on Node.js 25 and newer, npm install -g corepack first), then 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 website and agency dashboard origins, comma separated, …

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 the API's folder 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`. List the website's and the dashboard's addresses, comma separated.

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 essentials

The website has no listings and nobody can sign in

→ No database at /data/database.sqlite. Creating the tables, no data (set SEED_DEMO_DATA=true for the demo).

The database was created with tables only. That happens when the API container starts on a new volume without SEED_DEMO_DATA=true, when the full stack runs with SEED_DEMO_DATA=false in the .env beside docker-compose.yml, or without Docker when yarn db:sync ran instead of yarn seed. There are no listings and no account to sign in with.

• Without Docker: run yarn seed in the API's folder. It adds the demo agency and its accounts to the tables you have.
• Full stack in Docker: remove SEED_DEMO_DATA=false from the .env, then docker compose down -v and docker compose up. The data volume is created again with the demo agency.
• API container: remove the container, delete its volume, and run it again with -e SEED_DEMO_DATA=true, as in Start over below.

An existing database is never seeded again by the container, whatever SEED_DEMO_DATA says, so the variable only matters on a new volume.

Sign-in fails

• Check the account. The dashboard at port 3031 takes admin@velra.example with Admin@123, or agent@velra.example with Agent@123. The website has no accounts.
• "Invalid email or password" answers a wrong password, an unknown email and a database with no accounts alike. Check the points below in turn.
• The database has no accounts when it was created with SEED_DEMO_DATA=false. See The website has no listings and nobody can sign in, above.
• "Too many sign-in attempts. Try again in a few minutes." Ten failed sign-ins from one address within 15 minutes lock the form for that address until the oldest failure is 15 minutes old. Wait, or restart the API: the count is kept in its memory.
• "Network error. Please check your connection and try again" means the dashboard cannot reach the API: see the CORS problem below.
• You changed a password and no longer have it: start over with fresh demo data, below.

Sign-in fails

• Check the account and the route. Admins sign in at POST /api/auth/login; the seeded Super Admin is admin@velra.example with Admin@123. A failed sign-in answers 401 with the same message whether the email or the password is wrong.
• No account works at all: the database was created without the demo agency. Run yarn seed, or start the container with -e SEED_DEMO_DATA=true on a new volume.
• A `429` answer means one address failed 10 sign-ins within 15 minutes. It clears once the oldest failure is 15 minutes old, or when the API restarts. RATE_LIMIT_LOGIN changes the number.

Sign-in fails

The dashboard signs in against the Velra API, so the account has to exist there. On a seeded API, sign in with admin@velra.example and Admin@123. If no account works, either the API was started without its demo data (run yarn seed in its folder, or start its container on a new volume with -e SEED_DEMO_DATA=true), or the app cannot reach the API: see the next problem. The website has no accounts.

Pages say "We could not load this right now"

We could not load this right now
Access to XMLHttpRequest at 'http://localhost:8000/api/…' from origin 'http://localhost:3041' has been blocked by CORS policy

The website shows the first line, and the dashboard says "Network error", when the browser cannot use the API. The browser's console shows the second line when a frontend 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 and http://localhost:3031. A website or dashboard moved to another port, or served on your own domain, is refused until it is listed.

CORS_ORIGIN=http://localhost:3030,http://localhost:3041
FRONTEND_URL=http://localhost:3041

• Write each address exactly as the browser shows it, with the scheme and the port and without a trailing slash, comma separated. Then restart the API.
• FRONTEND_URL is the dashboard's address, which its live notifications connect from. Move it with the dashboard.
• For an API container, pass the same values with -e, such as -e CORS_ORIGIN=http://localhost:3030,http://localhost:3041.
• With the full stack in Docker you do not edit these: SITE_PORT, ADMIN_PORT, SITE_URL and ADMIN_URL in the .env beside docker-compose.yml set them.
• A frontend 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 frontend's NEXT_PUBLIC_API_BASE_URL names that API.

• Deploy it

A property page's tab says "Property details" in Docker

The website's own server reads the property's title for the browser tab, the first render of the page and the sitemap. Inside a container localhost is the container itself, so that server cannot reach an API on your computer at http://localhost:8000. The page still loads in the browser, which reaches the API directly.

Start the website container with the API's address as the server sees it:

docker run -p 3030:3030 -e API_INTERNAL_URL=http://host.docker.internal:8000/api --add-host=host.docker.internal:host-gateway velra-website

The full stack in Docker sets it for you (http://api:8000/api). Without Docker it is not needed.

Property photos do not load

The seeded photos are served by the API at /media/velra/…, and every photo address is built from PUBLIC_MEDIA_URL, which defaults to http://localhost:8000/media. A photo breaks when that address does not reach the API from the browser.

• The API runs on another port or domain. Set PUBLIC_MEDIA_URL to the API's public address followed by /media, for example -e PUBLIC_MEDIA_URL=http://localhost:8010/media on docker run -p 8010:8000. With the full stack in Docker, API_PORT and API_URL set it for you.
• The API moved after the first start. Restart it with the new PUBLIC_MEDIA_URL: on start it points every stored photo at that address, and its log says "Pointed … stored media URLs at …".
• Uploads to a bucket do not load. R2_PUBLIC_URL must be the bucket's public address, and the bucket must allow public reads.
• Photos load, but at full size. The frontends resize only photos from the https hosts in NEXT_PUBLIC_MEDIA_HOSTNAME (with Docker Compose, MEDIA_HOSTNAME), each written as the host alone and comma separated, such as api.your-agency.com,pub-1234.r2.dev. Any other photo, such as one from an API on localhost, loads as it is. Rebuild the frontend after changing it.

• Environment variables

A change to a frontend'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.

The staging studio or the assistant asks for a key

Generation needs a Google Gemini key
The assistant needs an AI provider key

The assistant answers with Google Gemini, OpenAI or DeepSeek and turns on with the key of any one of them in the API's .env: GOOGLE_API_KEY, OPENAI_API_KEY or DEEPSEEK_API_KEY, the three its notice lists. The staging studio generates with Google only, so it needs GOOGLE_API_KEY whatever else is set. In .env.example the three lines are commented out, so a copied file starts cleanly and both features stay off, with nothing billed.

• Remove the # in front of the line of each key you have, paste your real key over the example, and restart the API.
• With Docker Compose the API reads back-end/.env too, so docker compose up again is enough; a single API container needs --env-file .env -e NODE_ENV=production on its docker run.
• Reload the dashboard page after the restart.
• A model missing from the assistant's picker belongs to a provider whose key is not set: the picker lists only the models of providers with a key.

The assistant cannot answer with the chosen model

{provider} did not accept the API key, so {model} could not answer. Check that {variable} holds a valid {provider} key, then try again or pick a model from another provider.
The {provider} account behind this API key has no credit left, so {model} could not answer. Add credit or billing on that account, or pick a model from another provider.
{model} 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.
{provider} has no room for {model} right now. Try again in a minute, or pick another model from the list above the chat.

The assistant shows one of these in place of an answer when the provider behind the chosen model refuses the request, with Google, OpenAI or DeepSeek as the provider, the model's name, and the key's variable filled in. It runs only the model you picked: it never switches to another one by itself and never retries on its own, so fix the cause or pick another model in the list above the chat, then press Try again.

A viewing request or the contact form is refused

Choose a date and time at least one hour from now, in Dubai time.
Too many requests were sent from this connection. Please wait a few minutes and try again.

• Too soon. A viewing has to start at least an hour from now, in the agency's time zone (Asia/Dubai), whatever the visitor's own clock says.
• Too many requests. Each address may send five contact forms and five viewing requests in ten minutes. While you test, wait, or restart the API: the counts live in its memory.
• Behind a reverse proxy, every visitor can look like the proxy and share one allowance: see the next problem.

Every visitor gets "Too many" behind a proxy

The sign-in, the contact form and the viewing requests are limited per visitor address. Behind a reverse proxy, every visitor can look like the proxy's one address and share one allowance. Tell the API how many proxies stand in front of it:

TRUST_PROXY=1

RATE_LIMIT_LOGIN changes the number of failed sign-ins allowed. The counts live in the API's memory, so a restart clears them.

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 the API's .env, then run yarn seed (or yarn db:sync for the tables with no demo data).

• Check the five DB_* connection values and that DB_TYPE=mysql.
• With NODE_ENV=production the running API never creates tables, so one of those commands has to run before the first start (yarn seed:prod or yarn db:sync:prod after yarn build).
• The Docker image creates the database by itself only on SQLite. On MySQL, run the seed or the schema command once 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 unzip command fails or the folder looks different

caution: filename not matched:  velra-…zip

That message means two ZIPs of the same package sit in the folder, such as an older download next to the new one, and the * in the command matched both. Delete the older ZIP and run the command again, or type the full file name instead of the *.

Run the next 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 demo data

With the full stack in Docker, from the velra-real-estate-full-stack folder:

docker compose down -v
docker compose up

With a single API container, remove the container first (docker ps -a lists it, docker rm -f with its id removes it), then delete the velra-api-data volume and run it again. The full stack keeps its data in a different volume, velra-data, so this never touches it.

docker volume rm velra-api-data
docker run -p 8000:8000 -v velra-api-data:/data -e SEED_DEMO_DATA=true velra-api

Without Docker, stop the API, then in its folder:

rm -f database.sqlite* && yarn seed

In PowerShell:

Remove-Item database.sqlite*; yarn seed

Running yarn seed again on a database you keep is not a reset: it adds only what is missing and never resets a password. yarn db:reset drops every table, on SQLite and MySQL alike; run yarn seed after it.