Debugging rules

When a request is refused (or unexpectedly allowed), you need to know which rule decided and what it saw.

1. Read the error

A refusal in your app carries clues:

try {
  await pawabase.from("orders").update(id, { status: "paid" });
} catch (e) {
  if (e instanceof ApiError) {
    e.status;       // 403
    e.code;         // "forbidden"
    e.policy;       // the name of the rule that refused, when stated
    e.requestId;    // quote this to find the request
    e.details;      // extra structured data
  }
}

Python: the exception message and request_id where available.

2. Find the request in Studio

Project → Activity, then Requests. Search by the requestId, or filter by status (403, 404) and path. Open the request: it shows the method and path, who made it, the key used, the status, the timing and a note recording the policy decision: which rule decided and a short reason. This is the fastest way to answer “why”. You can also follow the request id through an event, a flow run and a webhook delivery to see the chain.

3. Reproduce it

In the API Explorer, sign in as the same kind of user and send the same request. Change one thing at a time. Reproducing as the real user (a test copy of the account) beats guessing.

4. Check what the rule saw

Most surprises are the rule seeing something other than you expect. Check each value it reads:

The rule reads	Check
`$auth.user_id`	`await pawabase.auth.getSession()` → `session.user.id`. Signed in as who you think?
`$auth.roles`	`user.roles`. The role may have been granted after the token was issued: sign out and in
`$auth.org`	`session.org`. Did they switch organization?
`$auth.aal`	`mfa.status().aal`. Did they complete the second step?
`$record.<column>`	The table editor: is the column actually filled?
`$input.<field>`	What exactly did the client send?
`$object.segments.0`	The exact key you used

5. Symptom checklist

”Empty list, but data exists”

The list rule filtered it out. Are you signed in as someone else? Is the owner column filled? Does the rule depend on $auth.org while the session has no organization?

“404 on a record I can see in Studio”

Studio sees all. A read rule is hiding it from this caller. Compare $record.owner_id with session.user.id.

”403 on create”

The create rule failed. Look at $input: the rule may constrain a field (status, quantity). Also check the key’s scopes if you use a restricted key.

”403 only in production”

The rule or a named rule it uses doesn’t exist or differs there. Rules belong to an environment; promote or compare definitions.

”Everyone can see everything”

Look for: a public rule; a missing rule on an enabled action (defaults to any signed-in user); eq of two nulls (no organization on either side); a rule using user_metadata that users can edit.

”Works for admin, not for staff”

A rule checks a role the staff user lacks. Or the role was granted and the token hasn’t refreshed.

”Works with a secret key, not with a user”

That tells you it is a rule (secret keys always pass). Walk the checklist above.

”Lists are short or total is null”

The rule is per-row. See How rules are evaluated.

6. Compare definitions

What you see on the table’s Access tab and on Access → Policies is what is in force.

7. Simulate before you ship

Test in development or a preview environment with real-looking users, then promote.

Testing

Prove the fix.

Activity

Find the request.

Getting started

Build rules in Studio

The language

Where rules apply

Recipes

Test and debug

1. Read the error

2. Find the request in Studio

3. Reproduce it

4. Check what the rule saw

5. Symptom checklist

”Empty list, but data exists”

“404 on a record I can see in Studio”

”403 on create”

”403 only in production”

”Everyone can see everything”

”Works for admin, not for staff”

”Works with a secret key, not with a user”

”Lists are short or total is null”

6. Compare definitions

7. Simulate before you ship

Testing

Activity

​1. Read the error

​2. Find the request in Studio

​3. Reproduce it

​4. Check what the rule saw

​5. Symptom checklist

​”Empty list, but data exists”

​“404 on a record I can see in Studio”

​”403 on create”

​”403 only in production”

​”Everyone can see everything”

​”Works for admin, not for staff”

​”Works with a secret key, not with a user”

​”Lists are short or total is null”

​6. Compare definitions

​7. Simulate before you ship

Testing

Activity

1. Read the error

2. Find the request in Studio

3. Reproduce it

4. Check what the rule saw

5. Symptom checklist

”Empty list, but data exists”

“404 on a record I can see in Studio”

”403 on create”

”403 only in production”

”Everyone can see everything”

”Works for admin, not for staff”

”Works with a secret key, not with a user”

”Lists are short or total is null”

6. Compare definitions

7. Simulate before you ship