From bbbba764e16067194215c017d18d5dc99dc66e18 Mon Sep 17 00:00:00 2001
From: "Sana (OpenClaw)" <sana@openclaw.local>
Date: Sun, 8 Feb 2026 15:41:28 +0000
Subject: [PATCH] docs: add troubleshooting note for NEXT_PUBLIC_API_URL

---
 README.md                      |  2 ++
 docs/troubleshooting/README.md | 17 +++++++++++++++++
 2 files changed, 19 insertions(+)
 create mode 100644 docs/troubleshooting/README.md

diff --git a/README.md b/README.md
index 6b9f0e6..fc602be 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 0000000..a6b6907
--- /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).