Query and data access errors

#A collection doesn't appear for some users

#Problem

A collection exists and works for you, but other users don't see it in the collection list or in GET /api/v1/collections. There is no error — the collection is missing from the response entirely.

#Cause

The collection list is filtered by permission. A collection only appears for users whose role has read access to it; roles without a read grant have the collection hidden from the list entirely. Users with the super_admin role bypass this filter and always see every collection.

#Fix

1. Open the collection's access settings and review the per-role access matrix.
2. Grant the affected role at least read access (All, Own, or Crew-scoped).
3. Confirm the result with the Effective Access tab of the Access Inspector (System → Access), which shows the effective CRUD permissions per resource for any user, role, or crew.

#Prevention

After creating a collection, set its access level for every role that needs it — new collections aren't automatically readable by all roles. See access control for how the per-role model works.

#Records return 404 record_not_found even though they exist

#Problem

A record is visible to one user but GET /api/v1/collections/:name/records/:id returns 404 with the code record_not_found for another. Lists and exports also show fewer records for some users.

#Cause

Row-level security. When a role's access to a collection is scoped to Own, the API filters out rows the user isn't allowed to see — and a filtered-out record is indistinguishable from one that doesn't exist. This is deliberate: revealing that a hidden record exists would leak information.

Exports apply the same row-level filters as list queries, so an export contains only the rows the exporting user can read.

#Fix

1. Check the collection's access settings for the user's role. If it says Own, the user only sees records they created, plus anything shared with them or with a flock they belong to.
2. If the user should see all records, change the role's access level to All.
3. If the record was meant to reach a flock, check that a share exists for it and that the user is an active member of that flock.

#Prevention

Use the Effective Access tab of the Access Inspector (System → Access) to simulate what a user, role, or crew can see before they report it as a bug.

#Browser requests fail with CORS errors after changing CORS settings

#Problem

You updated the CORS configuration, but cross-origin requests from the browser still fail with the old policy — or a brand-new instance rejects your frontend's origin for a short while after you save the config.

#Cause

The gateway caches CORS configuration in memory. A saved configuration is cached for up to 5 minutes; the "no configuration yet" state is cached for a shorter 30 seconds so a first-time setup takes effect quickly. Until the cache expires, responses use the previous policy.

Until you configure specific origins, the default policy allows all origins but disables credentials — so credentialed requests (cookies) fail even though the wildcard looks permissive.

#Fix

1. Wait up to 5 minutes after changing an existing CORS configuration (30 seconds after creating the first one), then retry.
2. If credentialed requests fail, configure an explicit origin allowlist — credentials are only enabled with specific origins, never with the wildcard.

#Prevention

Set up CORS with your frontend's exact origins before wiring up authenticated browser requests, and allow for the cache window when testing changes.

#Updated settings don't take effect immediately

#Problem

You saved a change on the Settings page, but API behaviour that depends on it doesn't change for a short while.

#Cause

Resolved settings are cached for up to 60 seconds so that every request doesn't hit the database. Any request served within that window uses the previous values.

#Fix

Wait a minute and retry. No restart or redeploy is needed — the cache expires on its own.

#Prevention

When scripting or testing settings changes, build in a delay of at least 60 seconds before asserting the new behaviour.