From 3f1c8a344fb76c0292514cf1278477cad6b25d4b Mon Sep 17 00:00:00 2001 From: Aleks Volochnev Date: Fri, 9 Oct 2026 14:15:44 +0200 Subject: [PATCH 1/4] Add a troubleshooting section to the getting started guide --- docs/getting-started.md | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/docs/getting-started.md b/docs/getting-started.md index bc46229..2bfe9b3 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -50,6 +50,34 @@ make test-frontend # type check and Vitest make test # both ``` +## Troubleshooting + +### Port 3000 or 8000 is already in use + +Stop the process that is using the port, or change the published port in `docker-compose.yml`, for example `"3001:3000"`. To see what is listening on a port, run `lsof -i :3000`. + +### The frontend shows an API error + +The frontend could not reach the backend. Check that the backend is running and healthy: + +```bash +curl http://localhost:8000/api/health +``` + +If you run the frontend with `npm run dev`, the backend must listen on port 8000, because Vite proxies `/api` requests there. + +### Browser requests fail with a CORS error + +Add the origin you are loading the frontend from to `CORS_ORIGINS`. See [configuration](configuration.md) for the format. + +### Start again with an empty database + +Stop the app and delete the SQLite file. When running locally, that is `backend/todos.db`. With Docker Compose, remove the containers and their volumes: + +```bash +docker compose down -v +``` + ## Next steps - Browse the [API reference](api-reference.md) to see every endpoint. From 2e599ec167d4f3ad7fdaba359b069c0a40147441 Mon Sep 17 00:00:00 2001 From: Aleks Volochnev Date: Fri, 9 Oct 2026 14:21:36 +0200 Subject: [PATCH 2/4] Cover both ports and custom database paths in the troubleshooting steps --- docs/getting-started.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/getting-started.md b/docs/getting-started.md index 2bfe9b3..ea07402 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -54,7 +54,7 @@ make test # both ### Port 3000 or 8000 is already in use -Stop the process that is using the port, or change the published port in `docker-compose.yml`, for example `"3001:3000"`. To see what is listening on a port, run `lsof -i :3000`. +Stop the process that is using the port, or change the published port in `docker-compose.yml`, for example `"3001:3000"`. To see what is listening on a port, run `lsof -i :3000` for the frontend or `lsof -i :8000` for the backend. ### The frontend shows an API error @@ -72,7 +72,7 @@ Add the origin you are loading the frontend from to `CORS_ORIGINS`. See [configu ### Start again with an empty database -Stop the app and delete the SQLite file. When running locally, that is `backend/todos.db`. With Docker Compose, remove the containers and their volumes: +Stop the app and delete the SQLite file. With the default configuration and a local run, that is `backend/todos.db`. If you changed `DATABASE_URL`, delete the file it points to instead. With Docker Compose, remove the containers and their volumes: ```bash docker compose down -v From 62b6c5d8de8e37faabb4855f5602c7145c698f39 Mon Sep 17 00:00:00 2001 From: Aleks Volochnev Date: Fri, 9 Oct 2026 21:18:15 +0200 Subject: [PATCH 3/4] Polish wording in the troubleshooting section --- docs/getting-started.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/getting-started.md b/docs/getting-started.md index ea07402..50ec00b 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -54,7 +54,7 @@ make test # both ### Port 3000 or 8000 is already in use -Stop the process that is using the port, or change the published port in `docker-compose.yml`, for example `"3001:3000"`. To see what is listening on a port, run `lsof -i :3000` for the frontend or `lsof -i :8000` for the backend. +Stop the process that is using the port, or change the published port in `docker-compose.yml`, for example `"3001:3000"`. To find out what is listening on a port, run `lsof -i :3000` for the frontend or `lsof -i :8000` for the backend. ### The frontend shows an API error From 3ed2658e3fe2f6a279fd046f6f1db2b7421778a1 Mon Sep 17 00:00:00 2001 From: Aleks Volochnev Date: Mon, 12 Oct 2026 14:57:50 +0200 Subject: [PATCH 4/4] Reword the CORS troubleshooting step --- docs/getting-started.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/getting-started.md b/docs/getting-started.md index 50ec00b..3256fe3 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -68,7 +68,7 @@ If you run the frontend with `npm run dev`, the backend must listen on port 8000 ### Browser requests fail with a CORS error -Add the origin you are loading the frontend from to `CORS_ORIGINS`. See [configuration](configuration.md) for the format. +Add the origin the frontend is served from to `CORS_ORIGINS`. See [configuration](configuration.md) for the format. ### Start again with an empty database