> ## Documentation Index
> Fetch the complete documentation index at: https://www.osohq.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Debugging a Policy

> Debug unexpected results from Oso Cloud using Logs and Explain.

When a user **gets access they shouldn’t** (or can’t access something they should), use **Logs** and **Explain** to trace the decision and find the cause.

## Example scenario

**Issue**: `User:bob` can **edit** `Document:foo` but should only have **read** access.

We’ll use Bob and `foo` as an example, but the same steps apply to any unexpected result.

## Step 1: Reproduce and locate the issue

Confirm the problem exists and that Oso Cloud is receiving the request.

1. Log in as Bob in your application.
2. Try to edit `foo`.
3. In Oso Cloud, open the **Logs** page.
4. Find the corresponding authorization request.

<img src="https://mintcdn.com/osoinc/HuMviHxd0NHscL55/images/debug_guide/logs_main.png?fit=max&auto=format&n=HuMviHxd0NHscL55&q=85&s=00687b8f292434ad1588546e07ca0963" alt="View of the logs page in Oso Cloud dashboard, indicating Bob can edit the document Foo" width="3578" height="1524" data-path="images/debug_guide/logs_main.png" />

The logs confirm `User:bob` has `edit` **and** `read` permissions on `Document:foo`:

<img src="https://mintcdn.com/osoinc/HuMviHxd0NHscL55/images/debug_guide/logs_detail.png?fit=max&auto=format&n=HuMviHxd0NHscL55&q=85&s=e31e1b4c3bc79a309d01fa8e4f9a8c5d" alt="Close-up of the log indicating Bob can edit document Foo" width="2582" height="462" data-path="images/debug_guide/logs_detail.png" />

**Key pint**: Oso Cloud received the authorization query and returned `allowed: true` — meaning the issue is in your **authorization model**, not your app code.

<Warning>
  If no log appears, the request never reached Oso Cloud. Check that your app calls `oso.authorize()` for this action.
</Warning>

## Step 2: Analyze with Explain

**Use the Explain feature** to understand why the authorization succeeded.

1. In the Logs page, click **"Try this query"** next to the unexpected result.
2. This opens the Explain page and re-runs the query.

<img src="https://mintcdn.com/osoinc/HuMviHxd0NHscL55/images/debug_guide/logs_detail_try.png?fit=max&auto=format&n=HuMviHxd0NHscL55&q=85&s=7763edda22925c5287e719ed73b4fcf0" alt="Logs page, highlighting a button to try the query" width="2582" height="462" data-path="images/debug_guide/logs_detail_try.png" />

Explain lists:

* The **facts** that contributed to the decision.
* The **policy rules** that matched.

<img src="https://mintcdn.com/osoinc/HuMviHxd0NHscL55/images/debug_guide/explain_success.png?fit=max&auto=format&n=HuMviHxd0NHscL55&q=85&s=99224923cc9f7dfe82a4a93bdb3475ec" alt="Explain page in Oso Cloud dashboard" width="3584" height="1728" data-path="images/debug_guide/explain_success.png" />

### Review contributing facts

Two facts granted Bob edit access to `Document:foo`:

<img src="https://mintcdn.com/osoinc/HuMviHxd0NHscL55/images/debug_guide/explain_success_detail.png?fit=max&auto=format&n=HuMviHxd0NHscL55&q=85&s=eebca1c3ef946786f87550f2c7fc650c" alt="Close-up of the facts that contributed to the query result" width="1430" height="730" data-path="images/debug_guide/explain_success_detail.png" />

**Root cause**: Bob can edit this document because it belongs to a folder marked as **public**.

### Check policy rules

The policy rules on the right show which rules allowed the action:

<img src="https://mintcdn.com/osoinc/HuMviHxd0NHscL55/images/debug_guide/explain_success_policy.png?fit=max&auto=format&n=HuMviHxd0NHscL55&q=85&s=4a7b1b90094eca8e00ad07e0f0b09167" alt="Close-up of the policy rules that contributed to the query result" width="1444" height="514" data-path="images/debug_guide/explain_success_policy.png" />

### Identify the fix

**Problem**: Users can perform *any* action on public folders (due to the wildcard `_`).

**Fix options**:

* Change the rule to only allow `read` actions on public folders
* Remove the public flag from folder `bar`

## Debug denied access (false negatives)

For actions that **should be allowed** but are denied, Explain still helps.

The left panel shows **attempts** to find a matching rule. Each attempt is one possible way to gain access.

<img src="https://mintcdn.com/osoinc/HuMviHxd0NHscL55/images/debug_guide/explain_failure.png?fit=max&auto=format&n=HuMviHxd0NHscL55&q=85&s=2c064000dde692de630d7e65f1d5564a" alt="Explain page highlighting the failed query attempts" width="3582" height="1712" data-path="images/debug_guide/explain_failure.png" />

### If the expected attempt appears

**Cause**: Required facts don't exist in Oso Cloud.

**Check for**:

* Missing `.tell()` calls in your backend.
* Facts with incorrect arguments or formatting.

### If the expected attempt does not appear

**Cause**: No matching rule in your policy.

**Fix**: Add the missing rule.

## Step 3: Verify data synchronization

**Check if your application data is in sync with Oso Cloud.**

If the logic looks right but results are wrong, facts may be out of sync.

### Check facts with CLI

Use the CLI to verify expected facts exist:

```bash theme={null}
oso-cloud get facts --filter "has_role(User:bob, _, Document:foo)"
```

### Set up data monitoring

If Oso Cloud is missing expected data, [set up a webhook](/develop/troubleshooting/logs) to monitor write requests and catch discrepancies early.

This feature is available to Growth plan customers. [Contact us on Slack](https://join-slack.osohq.com/) for setup assistance.
