SREDSimplify Engineering

Appearance

Troubleshooting ​

./start.sh fails immediately ​

Likely causes:

  • gum is not installed.
  • script is run in a non-interactive shell (no TTY).
  • Doppler CLI is not installed or not authenticated.
  • required language runtimes are missing.

Check:

bash
gum --version
doppler --version
uv --version
java -version
node -v

./start.sh says interactive terminal is required ​

start.sh is intentionally configured to require a TTY for gum interaction.

Use a local terminal session and run directly:

bash
./start.sh

Avoid running it through redirected or non-interactive contexts such as:

  • CI shell steps
  • detached background jobs
  • command pipelines that remove TTY interaction

Ports are already occupied ​

start.sh already tries to clear 3000, 8000, and 8080, but stale processes can still survive.

Check manually:

bash
lsof -i :3000
lsof -i :8000
lsof -i :8080

Then stop the listed processes and run ./start.sh again.

Frontend loads but API calls fail through the BFF ​

The proxy route depends on server-side environment variables such as:

  • BACKEND_ORIGIN
  • CF_CLIENT_ID
  • CF_CLIENT_SECRET

Symptoms include 500 Proxy misconfigured or 502 Upstream fetch failed from /api/bff/....

Check the frontend server logs and verify the backend origin is reachable from the Next.js runtime.

Login works locally but task runs fail ​

That usually means the public backend is healthy, but the Java-to-Python internal boundary is broken.

Check:

  • Python service is actually running.
  • INTERNAL_API_TOKEN matches on both sides.
  • backend can reach PYTHON_SERVICE_BASE_URL.

File upload succeeds but indexing never completes ​

Check these layers in order:

  1. upload was confirmed, not only presigned.
  2. file metadata moved from PENDING to CONFIRMED / INDEXING.
  3. Redis stream dispatch succeeded.
  4. python worker is running and consuming work.

If the object upload worked but confirmation did not, the file bytes may exist in R2 while the app still treats the file as incomplete.

Services stop unexpectedly when terminal closes ​

start.sh now owns process lifecycle for that run.

  • Closing the terminal, or pressing Ctrl+C, triggers best-effort cleanup of started services.
  • To keep services alive, keep the original terminal session open.
  • If a warning reports remaining occupied ports, clear those processes manually.

Docs build fails ​

Run:

bash
cd docs
npm run docs:build

Common causes:

  • broken markdown links.
  • sidebar entry points to a file that does not exist.
  • malformed frontmatter.

When adding docs, always rebuild the site before considering the update complete.