> ## Documentation Index
> Fetch the complete documentation index at: https://forest-audit-trail.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Common issues and how to fix them

## 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:

```nginx theme={null}
fastcgi_buffering off;
proxy_buffering off;
```

**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.

```javascript theme={null}
const agent = createAgent({
  // ...
  instantCacheRefresh: false,
});
```

## Agent health check

Test that your agent is reachable:

```bash theme={null}
curl http://localhost:3310/forest
# Should return: {"meta":{"name":"@forestadmin/agent",...}}
```

In production, test with HTTPS:

```bash theme={null}
curl https://your-agent.yourcompany.com/forest
```

## 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](https://community.forestadmin.com). The team responds quickly.