Troubleshooting

A port is already in use

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 line comes from Docker, the second from yarn dev or yarn start. Another program already listens on 3030: often an earlier run of the site, or another project's dev 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 name or id (docker ps lists them). Then start the site again.
3. 03

   Or run the site on another port

   With Docker, change the number on the left of -p only; the right one is the port inside the container and stays 3030:

   Terminalin juicyCopy

   docker run -p 3041:3030 juicy

   Without Docker:

   Terminalin juicyCopy

   yarn dev -p 3041

   For the production build, yarn start -p 3041.

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

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 juicy ., then docker run -p 3030:3030 juicy.

The Docker build fails

The first build downloads the Node.js image and every dependency, then builds the site. 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 `yarn build` after you changed the code: the error above that line names the file. Run yarn typecheck without Docker to see every type error at once.
• It fails at the same step every time: build again without the cache.

docker build --no-cache -t juicy .

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…

The template 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, install it first with npm install -g corepack.

The cans do not appear

Loading models...

The page stays on its loader, or shows the background and the text with no cans. The wheel appears only once the first can and the lighting map have both loaded, so one failed file keeps it hidden.

• A model path is wrong. Each can's .glb file is listed in src/features/carousel/constants/juiceCans.ts and served from public/. A renamed or moved file answers 404.
• The lighting map is missing. It is public/assets/hdri/forest_slope_1k.hdr, named in src/features/carousel/constants/environment.ts. Keep the file, or change both together.
• WebGL is off. Turn on hardware acceleration in the browser's settings, or try another browser.

Open the browser's developer tools, Network tab, and reload: a failed request names the missing file. Everything the page loads ships in the folder, so it needs no outside service.

A change does not show

• With Docker: the image holds a copy of the site from when you built it. Run docker build -t juicy . again, then start a new container.
• With `yarn start`: run yarn build again first. Only yarn dev picks up changes by itself.
• A new 3D model or image looks old: the browser keeps files from public/. Reload without the cache (Ctrl+Shift+R, or Cmd+Shift+R on a Mac), or give the new file a new name.

The site reads no environment variables. If you add one whose name starts with NEXT_PUBLIC_, Next.js writes its value into the page at build time, so a new value needs a new build too.

A text shows as its key

juices.lemonGinger.name

The page shows the name of a text instead of the text, and the browser console logs MISSING_MESSAGE. The key is missing from one of the message files, often after a flavour got a new id. Add it to both messages/en.json and messages/ar.json, with the same path in each.

• Swap a flavour

The site does not answer on a hosting service

yarn start always listens on port 3030: the script sets it with -p 3030, which wins over a PORT variable. A host that gives the app its own port in PORT then finds nothing there. Tell the host the app listens on 3030, or use this as its start command:

yarn next start -p $PORT

• Put it online