Skip to main content

​
CORS errors

CORS is the most common issue when setting up the Forest agent. Open your browser’s Developer Console (Network tab) to detect it. Check:
  • The Forest agent is mounted before any other middleware. In NestJS specifically, the Nest App Factory’s CORS configuration can interfere with @forestadmin/agent. Configure it after mounting the agent.
  • If you cannot mount the agent first and your own CORS middleware answers the preflight requests, its allowedHeaders list must include every header the Forest UI sends that requires allow-listing: Authorization, Content-Type, Forest-Context-Url, and Forest-Projection — this last one is sent to agents that announce a projection-via-header capability, and a missing entry breaks every view that sends it. With canUseProjectionViaHeader, that is the record details view. With canUseProjectionViaHeaderOnList — announced from @forestadmin/agent@1.94.0 and forest_admin_agent 1.38.0 — it also covers collection lists, related-data lists and CSV exports, so records cannot be browsed at all, not just opened. Upgrading past those versions is what makes the missing entry visible, so check this list after an agent upgrade. The OPTIONS request still returns 204 in that case: the browser rejects the preflight response and cancels the actual request, with a console error naming the header (Request header field forest-projection is not allowed by Access-Control-Allow-Headers in preflight response). To identify which middleware answered the preflight, read the Access-Control-Allow-Headers response header: a fixed list comes from your middleware, an echo of the requested headers comes from the agent.
  • Your server is up and running. Test it by calling the /forest endpoint: curl http://localhost:3310/forest

​
403 Forbidden errors after permission changes

If you add users, create collections, or change permissions in Forest and start getting 403 errors that only go away after restarting your agent, this is likely caused by SSE (Server-Sent Events) buffering in a reverse proxy. Forest uses SSE to push permission updates to your agent in real time. Some reverse proxies buffer SSE connections and prevent the agent from receiving updates. To confirm: Restart your agent. If the 403 errors disappear, SSE buffering is the cause. Fix option 1: Disable buffering in your reverse proxy: For nginx:
Fix option 2: Fall back to TTL-based cache: Set instantCacheRefresh: false in your agent initialization options. This disables SSE and uses a periodic cache refresh instead.

​
Agent health check

Test that your agent is reachable:
In production, test with HTTPS:

​
Schema not updating

If your database schema changes are not reflected in Forest:
  1. Make sure your agent is restarted after schema changes
  2. Check that isProduction is set correctly. In production mode, the schema is not re-introspected on startup
  3. Delete .forestadmin-schema.json and restart to force a full schema refresh (development only)

​
Need more help?

Post your question on the Forest Community Forum. The team responds quickly.