From aef70bbaf39fe3c640f1fce084d62137d8533734 Mon Sep 17 00:00:00 2001
From: wuyangfan <yangfan.wu@succaiss.com>
Date: Fri, 12 Jun 2026 23:08:48 +0800
Subject: [PATCH] docs: add troubleshooting faq

---
 README.md | 60 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 60 insertions(+)

diff --git a/README.md b/README.md
index 1154b29..b8f2a69 100644
--- a/README.md
+++ b/README.md
@@ -110,6 +110,66 @@ The frontend expects the API at `http://localhost:5000` unless `VITE_API_URL` is
 - `npm run dev` start Vite dev server
 - `npm run build` build production assets
 
+## Troubleshooting / FAQ
+
+### Port 5000 or 5173 is already in use
+
+Stop the process using the port, then restart the affected dev server:
+
+```bash
+lsof -ti :5000 | xargs kill
+lsof -ti :5173 | xargs kill
+```
+
+If you intentionally run the API on another port, update `PORT` in `.env` and
+point the frontend at it with `VITE_API_URL`, for example
+`VITE_API_URL=http://localhost:5001`.
+
+### The frontend shows CORS errors
+
+Make sure the backend is running before the frontend:
+
+```bash
+npm run dev
+```
+
+Then confirm `.env` includes the frontend origin you are using:
+
+```env
+CLIENT_ORIGINS=http://localhost:5173,http://127.0.0.1:5173
+```
+
+For a custom Vite port, add that origin to `CLIENT_ORIGINS` or set
+`VITE_API_URL` to the API URL the browser should call.
+
+### Requests fail with `Invalid token`
+
+This usually means the browser still has an old JWT after changing
+`JWT_SECRET`, reseeding data, or switching environments. Clear local storage,
+then sign in again with one of the seeded demo accounts:
+
+```javascript
+localStorage.clear();
+```
+
+You can run that command in the browser devtools console, or use the app's
+logout flow before signing in again.
+
+### Database connection fails on startup
+
+If you do not need Postgres locally, remove or comment out `DATABASE_URL` in
+`.env` and use the default JSON store:
+
+```bash
+npm run seed
+npm run dev
+```
+
+If you do want Postgres, verify the connection string with your provider,
+including username, password, database name, host, and `sslmode=require` when
+required. The API creates tables automatically after a valid `DATABASE_URL`
+connects.
+
 ## API summary
 
 ### Auth