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 Hollina, 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 Hollina again.
3. 03

   Or run Hollina on other ports

   With the full stack in Docker, create a file named .env in the hollina-vacation-rental-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.

   hollina-vacation-rental-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 hollina-vacation-rental-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 company. 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 booking 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 stays 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 stays and no account to sign in with.

• Without Docker: run yarn seed in the API's folder. It adds the demo company 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 company.
• 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@hollina.example with Admin@123, or manager@hollina.example with Manager@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 stays and nobody can sign in, above.
• "Too many attempts. Please try again later" 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 next problem.
• 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@hollina.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 company. 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 Hollina API, so the account has to exist there. On a seeded API, sign in with admin@hollina.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 "Something went wrong. Try again."

Something went wrong. Try again.
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, and SITE_URL the website's, where a payment processor sends the guest back. Move each with its app.
• 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 stay page's tab says "Stay" in Docker

The website's own server reads the stay's title for the browser tab, the first render of the home and stay pages 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 hollina-website

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

Stay photographs do not load

The seeded photographs are served by the API at /media/hollina/…, and every photograph address is built from PUBLIC_MEDIA_URL, which defaults to http://localhost:8000/media. A photograph 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 photograph 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.
• Photographs load, but at full size. The frontends resize only photographs 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-company.com,pub-1234.r2.dev. Any other photograph, such as one from an API on localhost, loads as it is. Rebuild the frontend after changing it.

• Environment variables

A stay page says "The map could not be loaded."

The map draws its tiles from OpenFreeMap by default, so it needs internet access, and the service promises no uptime. Check the connection, or set NEXT_PUBLIC_MAP_STYLE_LIGHT (and NEXT_PUBLIC_MAP_STYLE_DARK for the dark theme) to another provider's MapLibre style and rebuild the website.

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.

A paid booking stays pending

We are confirming your payment.
This is taking longer than usual.

What confirms a card or PayPal booking is the processor's webhook, never the guest returning to the site. Until it arrives, the booking page waits, the booking stays pending and holds its nights for 30 minutes, and then a sweep cancels it as expired.

• Stripe: STRIPE_WEBHOOK_SECRET is missing or wrong, so every Stripe webhook is refused. Locally, run stripe listen --forward-to localhost:8000/api/webhooks/payments/stripe, put the secret it prints in the API's .env and restart the API. On a server, create the endpoint in Stripe at your API's public address.
• PayPal: the return page captures the order through POST /api/bookings/:reference/settle; the webhook needs PAYPAL_WEBHOOK_ID, the id of a subscription to PAYMENT.CAPTURE.COMPLETED at /api/webhooks/payments/paypal.
• stripe trigger checkout.session.completed confirms nothing: a triggered event carries no booking reference. Complete a real test checkout in the browser instead, with the card 4242 4242 4242 4242.

• Bookings and payments

A booking, a question or a review is refused

Your payment was declined. Try another card or another way to pay.
That payment method is not available. Choose another way to pay.
Too many requests were sent from this connection. Please wait a few minutes and try again.
The selected dates do not meet the minimum stay.

• Declined: without a processor the shipped simulator declines a card number ending in 0, on purpose, so the failure path can be seen. Any other number is accepted.
• Payment method not available: the API no longer takes that method, such as PayPal once only Stripe is configured, card once only PayPal is, or pay on arrival after its switch was turned off. Nothing was written and no nights are held: reload the checkout, which then offers only what the API takes.
• A question or a review is refused: a question's message runs from 10 to 4000 characters and a review's comment from 10 to 2000, and the form says so under the field before sending.
• Too many requests: each address may send five bookings, five questions and five reviews in ten minutes. While you test, wait, or restart the API: the counts live in its memory.
• Dates refused: a stay has its own minimum number of nights and maximum guests, a check-in cannot be in the past, and nights another booking or a block holds are taken. Bookings cover [check-in, check-out), so a guest may arrive on the day another leaves.
• Cancelling online refused: a guest cancels from their booking page while it is pending or confirmed and check-in is at least seven days away; after that the page says to contact the host, who can still cancel from the dashboard.
• 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 checkout, the question form and the review form 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.

The assistant says it is not connected yet

The assistant is not connected yet. Add a Google Gemini key as GOOGLE_API_KEY in the API's .env file, restart the API, then ask again.

The assistant answers with Google Gemini only, on the key in GOOGLE_API_KEY in the API's .env. In .env.example that line is commented out, so a copied file starts cleanly with the assistant off and nothing billed.

• Remove the # in front of GOOGLE_API_KEY, paste your real key from Google AI Studio 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.

The assistant cannot answer with the chosen model

{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.

Google refused the request because the key's allowance for that model is used up for now, or the model has no capacity at the moment, and the message names the model. The assistant runs only the model you picked: it never switches to another one by itself and never retries on its own. Pick another model in the list above the chat, or wait a few minutes, then press Try again. Allowances are counted per model, so another one often still answers.

In demo mode the assistant asks for the visitor's own 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 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:  hollina-…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 hollina-vacation-rental-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 hollina-api-data volume and run it again. The full stack keeps its data in a different volume, hollina-data, so this never touches it.

docker volume rm hollina-api-data
docker run -p 8000:8000 -v hollina-api-data:/data -e SEED_DEMO_DATA=true hollina-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 never resets a password and adds nothing twice, it writes the shipped stays, bookings and company settings back to their shipped values, and it keeps the stays, bookings and other rows you created. yarn db:reset drops every table, on SQLite and MySQL alike; run yarn seed after it.