Troubleshooting Hub

This guide provides solutions for the most common issues encountered during platform development and integration.

---

🛡️ Authentication & SSO

1. "401 Unauthorized" from Satellite API

Symptom: Your satellite UI loads, but API calls fail with 401.

• Cause A: VITE_SHELL_API_URL is wrong.
• Fix: Check ui/.env.development. It must point to the Shell's API (e.g., http://localhost:3000).
• Cause B: Satellite API cannot reach Shell's JWKS.
• Fix: Check api/.env. Ensure APP_ENV_SHELL_JWKS_URL is reachable from the satellite's terminal.

2. UserMenu shows "U" instead of Name/Email

Symptom: The Shell header shows a generic "U" icon.

• Cause: The UserProvider fallback failed.
• Fix: Ensure your token-broadcast.ts includes the getUserFromShellJwt() function which decodes the token directly from localStorage['token'].

---

🧩 Module Federation

3. White Screen in Shell (No Errors)

Symptom: Navigating to your app shows a blank workspace.

• Cause: The remoteEntry.js URL is wrong in the Shell DB.
• Fix: Use the veni register CLI again or check the apps table in the Shell database.

4. "Cannot read properties of null (reading 'useState')"

Symptom: The app crashes only when loaded inside the Shell.

• Cause: React version mismatch or "Double React" issue.
• Fix: Ensure your vite.config.ts has shared: {} for React. Do not use singleton: true, import: false unless you are matching the Shell's exact build.

---

📦 Infrastructure & Docker

5. "Relation 'xxx' does not exist"

Symptom: Database queries fail after starting the app.

• Cause: Migrations haven't run.
• Fix: Run bun run db:migrate in your api/ directory.

6. Container keeps restarting (CrashLoopBackOff)

Symptom: docker ps shows the container is down or restarting.

• Cause: Missing environment variable.
• Fix: Check the logs with docker-compose logs <service-name>. Look for Zod validation errors.

---

📡 Networking & Routing

7. CORS Errors in Browser

Symptom: Browser blocks requests from UI to API.

• Fix: The Shell API and Satellite APIs must allow the Shell's origin. Ensure VITE_SHELL_URL is correctly set in your environment.

8. 404 on remoteEntry.js

Symptom: The network tab shows 404 for the federation entry file.

• Fix: Ensure your UI build has base: '/' and publicPath: '/' in vite.config.ts.

---

Still Stuck?

If you can't find the solution here, open Gemini CLI or Claude Code and paste the exact error message. The AI can analyze your specific logs.