diff --git a/README.md b/README.md
index 6b9f0e6a..fc602be7 100644
--- a/README.md
+++ b/README.md
@@ -160,6 +160,8 @@ make check
 
 ## Troubleshooting
 
+More: [`docs/troubleshooting/README.md`](./docs/troubleshooting/README.md)
+
 ### Frontend keeps redirecting / Clerk errors
 
 You likely have `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY` set (even to a placeholder). To run without Clerk:
diff --git a/docs/troubleshooting/README.md b/docs/troubleshooting/README.md
new file mode 100644
index 00000000..a6b69079
--- /dev/null
+++ b/docs/troubleshooting/README.md
@@ -0,0 +1,17 @@
+# Troubleshooting
+
+## Activity feed is blank / frontend API calls fail
+
+**Symptoms**
+- Activity feed shows no items.
+- The browser console/network tab shows failed requests to `/api/v1/*`.
+
+**Cause**
+- `NEXT_PUBLIC_API_URL` is missing/blank/incorrect. The frontend uses this variable to build API URLs.
+
+**Fix**
+- Local dev: set `NEXT_PUBLIC_API_URL=http://localhost:8000` in `frontend/.env.local`.
+- Docker Compose (self-host): set `NEXT_PUBLIC_API_URL=http://localhost:8000` in the root `.env` used by compose (or update it to match your actual backend host/port).
+
+Notes:
+- `NEXT_PUBLIC_API_URL` must be reachable from the browser (not just from within containers).