UNIPH.AI
HomeAll docsOpen Workspaces

Netlify Troubleshooting

Netlify: Frontend Not Displaying — Troubleshooting

1. Base directory must be frontend

This is the most common cause. If the frontend doesn’t display (blank, 404, or wrong content), Netlify is probably building from the repo root instead of the frontend app.

  1. Open Netlify → your frontend site.
  2. Site configuration → Build & deploy → Build settings.
  3. Set Base directory to: frontend
  4. Leave Publish directory empty (the Next.js plugin sets it).
  5. Save and trigger a new deploy (Deploys → Trigger deploy → Deploy site).

Without this, npm run build runs from the repo root (no Next.js there), so the build fails or deploys the wrong thing.

2. Check the build log

In Netlify: Deploys → click the latest deploy → Build log.

  • Build failed: Look for the first red error (e.g. npm run build not found, missing module, Node version). Fix that and redeploy.
  • Build succeeded: Go to step 3.

Common failure: "npm run build" not found or script missing. That usually means Netlify is building from the repo root instead of the frontend/ folder. Fix: set Base directory to frontend (see below).

3. Environment variable and redeploy (required for workspaces/API)

If you see "Unable to connect to the API" or "Ensure the backend is running at http://localhost:3001", you must set NEXT_PUBLIC_API_URL to your deployed backend URL. The default localhost:3001 only works locally; in production it points nowhere.

  1. Deploy your backend to a second Netlify site (see backend/DEPLOY_NETLIFY.md).
  2. Note the backend URL (e.g. https://uniph-api.netlify.app).
  3. In your frontend Netlify site: Site settings → Environment variables → add:
    • Key: NEXT_PUBLIC_API_URL
    • Value: https://your-backend-site.netlify.app (your actual backend URL)
  4. Trigger deploy so the new value is baked in (Next.js reads this at build time).

NEXT_PUBLIC_API_URL is baked in at build time. If you added or changed it after the first deploy:

  1. Site settings → Environment variables → confirm NEXT_PUBLIC_API_URL is set (e.g. to your backend URL).
  2. Deploys → Trigger deploy → Deploy site.

Wait for the new deploy to finish, then reload the site.

Important: NEXT_PUBLIC_API_URL must be an HTTP(S) API URL (e.g. https://your-api.railway.app), not your DATABASE_URL. If you accidentally set NEXT_PUBLIC_API_URL to a Postgres connection string, you'll get: TypeError: Request cannot be constructed from a URL that includes credentials. Fix: set NEXT_PUBLIC_API_URL to your backend API URL (the same host that serves /api/health), then redeploy.

Docker: When using docker compose up, the frontend container uses API_SERVER_URL=http://backend:3001 (set in docker-compose.yml) for server-side fetches. This is required so the Next.js server can reach the backend. Client-side fetches use NEXT_PUBLIC_API_URL (localhost:3001) from the browser.

4. Blank or broken page (build succeeded)

  • Open the site URL and check the browser Console (F12 → Console) for errors.
  • Confirm your backend is deployed and reachable at the same URL you set in NEXT_PUBLIC_API_URL (e.g. open https://your-api-url/api/health in a new tab).
  • Try a hard refresh (Ctrl+Shift+R or Cmd+Shift+R) or an incognito window in case of cache.

Quick checklist (frontend not displaying)

  • [ ] Base directory = frontend (Build settings). If it was wrong, trigger a new deploy.
  • [ ] Publish directory is empty (Next.js plugin sets it; do not set to public).
  • [ ] Base directory = frontend.
  • [ ] Latest build log shows “Build succeeded” and a Next.js/OpenNext build.
  • [ ] NEXT_PUBLIC_API_URL is set if the app calls the API; redeploy after changing it.
  • [ ] Backend is optional for the landing page; the frontend should still display without it.