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: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. Another program already listens on 3030, 3031 or 8000: often an earlier run of Learnio, 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, docker compose down in its folder, or docker stop for a container you started with docker run. Then start Learnio again.
3. 03

   Or run Learnio on other ports

   With the full stack in Docker, create a file named .env in the learnio-lms folder, next to docker-compose.yml, with the port you need. SITE_PORT moves the student site, ADMIN_PORT the admin and API_PORT the API; the addresses the apps use follow by themselves.

   learnio-lms/.envCopy

   ADMIN_PORT=3041

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

   Terminalin learnio-lmsCopy

   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.

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 data. The site and the admin 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.

corepack enable

On Node 26, which no longer ships Corepack, install it first with npm install -g corepack. yarn install ending with "Done with warnings" is expected; a real failure ends with "Failed with errors".

The API stops before starting

✖ The API cannot start. Fix these in back-end/.env:

The API checks its settings first and lists what to fix. The usual causes:

• There is no `.env` file. Create it in back-end/ with cp .env.example .env.
• `JWT_SECRET` is empty, or is the example value with `NODE_ENV=production`. Generate your own secret.
• `CORS_ORIGIN` is empty with `NODE_ENV=production`. List the student site and the admin, comma separated.
• `DB_TYPE` is not `sqlite` or `mysql`.

• API essentials

Sign-in fails

• Check the account and the app. Staff accounts sign in to the admin at port 3031: admin@learnio.com with Admin@123. The demo student signs in to the student site at port 3030: demo@learnio.com with Demo@123.
• Check the API's log. "The database has no accounts, so nobody can sign in" means the demo data was never added. Without Docker, run yarn seed in back-end/. With Docker, the volume was created with SEED_DEMO_DATA=false.
• "The database has no tables yet" means the schema was never created: run yarn seed in back-end/ and restart the API.
• You changed the super admin's password and no longer have it: start over with fresh demo data, below.
• "That email and password combination didn't work" is the one answer for an unknown email and for a wrong password alike, so check both.
• "Too many attempts" means one address made more than 10 tries on a sign-in or password form within a minute, which a live server refuses with 429. Wait a minute and try again.

Sign-in fails

• Check the API's log. "The database has no accounts, so nobody can sign in" means the demo data was never added: run yarn seed, or start the Docker container with -e SEED_DEMO_DATA=true on a new volume.
• "The database has no tables yet" means the schema was never created: run yarn seed and restart the API.
• Check the account. The super admin is admin@learnio.com with Admin@123, the demo student demo@learnio.com with Demo@123. A failed sign-in answers 401 with the same message whether the email or the password is wrong.
• A `429` answer means one address made more than 10 tries on a sign-in, sign-up or password route within a minute. The Retry-After header says how many seconds to wait.

Sign-in fails

On the in-browser mock, any email and password sign you in as the super admin. Once you connect an API, sign in with an account that exists in it; the demo super admin is admin@learnio.com with Admin@123.

A "Sample data" notice appears

The frontend could not reach the API, so it is showing its bundled sample data instead.

1. 01

   Check that the API answers

   Open localhost:8000/api/healthLocal. It should answer with a status of ok.
2. 02

   Check the frontend's API address

   NEXT_PUBLIC_API_BASE_URL in the frontend's .env must be the API's address including /api, e.g. http://localhost:8000/api.
3. 03

   Restart the frontend

   The address is compiled in. Restart yarn dev after changing it; with Docker, run docker compose up --build again.

Course images are broken after connecting R2

With R2_* keys in back-end/.env, the API serves media from your bucket, and the frontends only display images from hosts they were built to trust. Without that host, every course thumbnail shows its alt text instead of the picture.

1. 01

   Name your bucket's public host

   With Docker, put MEDIA_HOSTNAME=your-bucket.r2.dev in a .env file next to docker-compose.yml. Without Docker, set NEXT_PUBLIC_MEDIA_HOSTNAME in each frontend's .env. Write the host only, without https://.
2. 02

   Rebuild the frontends

   The host is compiled in. Run docker compose up --build again, or restart yarn dev and rebuild for production.

   Expected result: Course thumbnails load from your bucket.

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 demo data

With Docker, from the learnio-lms folder:

docker compose down -v
docker compose up

Without Docker, stop the API, then:

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: roles keep the permissions you gave them and settings keep the values you saved. Only a fresh database brings the shipped ones back.