Policy Tracing and Explainability¶

Privacera PolicySync connectors emit structured audit events that explain how policies are loaded, applied, and enforced on target data services. These events give administrators and security teams a granular, auditable view of grant and revoke operations, changelog execution, loader statistics, and long-running work progress.

PolicySync writes events to the policysync_audit stream. Audit Server indexes them into Apache Solr by default and can forward the same JSON payloads to Amazon SQS, Amazon SNS, or object storage (Amazon S3, Azure Blob, Google Cloud Storage) when those destinations are configured.

Every ACCESS, POLICY_RESPONSE, and ON_DEMAND event lists its outcomes, on success as well as on failure, as numeric response codes in extraInfo.response[]. A LOADER event lists one when its load failed, and a TEMPLATE_UPDATE_RESPONSE event lists the failures of a template update.

What you can trace¶

Event destinations¶

For Ranger plugin access audits (distinct from PolicySync connector tracing), see Audit log JSON format.

Event JSON format¶

The same JSON payload shape is used when Audit Server indexes events into Solr and when events are forwarded to Amazon SQS, Amazon SNS, or object storage.

Wire contract¶

Event types¶

The ACCESS, POLICY_RESPONSE, and ON_DEMAND events list their outcome codes in extraInfo.response[]. A failed LOADER event can list one, and a TEMPLATE_UPDATE_RESPONSE event lists its failures. For the codes by event type, see Response codes; to find the ACCESS events behind a failure, see Link a failure to its ACCESS audits.

Common fields¶

All event types include these fields.

Status¶

Changelogs and changeLogType¶

PolicySync records work in changelogs. For each stream of updates it maintains a changelog and applies deltas to the target service.

Common changeLogType values¶

Canonical changeLogType strings use UPPERCASE with underscores. Privacera may add new values in future releases.

Correlating changeLogId¶

When an event includes changeLogId, use these rules together with ACCESS and CHANGELOG events:

Type-specific fields¶

POLICY_RESPONSE¶

Emitted once per policy when a RANGER_POLICIES changelog completes. Per-policy ACL rollups live in extraInfo.aclsExecuted; the CHANGELOG completion event carries id and version summaries only.

extraInfo.aclsExecuted¶

Other extraInfo fields¶

ACCESS¶

Emitted after a grant or revoke (or identity operation) is executed on the target service.

Typical field mapping (connector-specific)¶

extraInfo for ACCESS¶

CHANGELOG¶

extraInfo for CHANGELOG¶

Each element of extraInfo.policies[]:

Each principal kind under extraInfo.principals (users, groups, roles):

LOADER¶

loaderType values¶

extraInfo for LOADER¶

Each resource or tag type under extraInfo.resources or extraInfo.tags:

Ranger principal loader counts¶

Each principal kind under extraInfo.principals (users, groups, roles) of a LOAD_RANGER_PRINCIPALS audit:

A principal change that fails is tried again on the next sync. When some changes fail, the audit is still COMPLETED and msg lists the failed changes. It is FAILED when every change failed or the sync stopped with an error.

PROGRESS¶

extraInfo.progress¶

Example events¶

Values such as IDs, names, and times are examples. The examples of failures show only the fields that carry the outcome and the fields that link events together.

POLICY_RESPONSE¶

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

{
  "eventType": "POLICY_RESPONSE",
  "evtTime": "2025-11-14T01:31:00.170Z",
  "timeTakenMs": 100,
  "status": "COMPLETED",
  "msg": "Applied Ranger policy policy1.",
  "connectorType": "lakeformation",
  "connector": "Lakeformation-instance1",
  "changeLogId": 22576,
  "changeLogType": "RANGER_POLICIES",
  "policyId": 1,
  "policyVersion": 3,
  "policyLabel": "correlationId",
  "policyName": "policy1",
  "extraInfo": {
    "aclsExecuted": {
      "total": 10,
      "applied": 10,
      "failed": 0,
      "skipped": 0,
      "timeTakenMS": 120
    },
    "response": [
      { "code": 2001, "msg": "Resource synced; access grants applied", "origin": "AWS_LAKEFORMATION", "count": 10 }
    ]
  }
}

POLICY_RESPONSE — grants partially applied (Databricks Unity Catalog)¶

A policy where four ACL operations applied, four failed in three different ways, and one grant was skipped because the grantee owns the resource. The counts add up to 8 ACL operations plus 1 owner skip. Only the 5001 entry is worth retrying.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

{
  "eventType": "POLICY_RESPONSE",
  "evtTime": "2026-10-23T09:12:44.020Z",
  "status": "GRANT_PARTIALLY_APPLIED",
  "connectorType": "databricks_unity_catalog",
  "connector": "dbx-uc-prod",
  "changeLogId": 48213,
  "changeLogType": "RANGER_POLICIES",
  "policyId": 812,
  "policyVersion": 7,
  "policyName": "finance-analysts-read",
  "extraInfo": {
    "aclsExecuted": { "total": 8, "applied": 4, "failed": 4, "skipped": 0 },
    "ownerIgnore": { "count": 1, "reason": "Resource owner is not mapped to a managed Ranger user" },
    "policy": { "createTime": "2026-09-30 11:02:10", "updateTime": "2026-10-23 09:12:30" },
    "response": [
      { "code": 2001, "msg": "Resource synced; access grants applied", "origin": "DBX", "count": 4 },
      { "code": 4503, "msg": "Grantee principal not found in the target service", "origin": "DBX", "serviceCode": "PRINCIPAL_DOES_NOT_EXIST.PRINCIPAL_DOES_NOT_EXIST", "count": 2 },
      { "code": 4502, "msg": "Failed to grant", "origin": "DBX", "serviceCode": "UNSUPPORTED_FEATURE", "count": 1 },
      { "code": 5001, "msg": "Transient backend or infrastructure failure", "origin": "DBX", "serviceCode": "INTERNAL_ERROR", "count": 1 },
      { "code": 1004, "msg": "Grant skipped: the resource owner is not mapped to a managed Ranger user", "origin": "PRIVACERA", "count": 1 }
    ]
  }
}

POLICY_RESPONSE — no change¶

A Ranger policy change that applied no grants carries one entry, with count 0:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

{
  "eventType": "POLICY_RESPONSE",
  "status": "COMPLETED",
  "connector": "dbx-uc-prod",
  "changeLogId": 48214,
  "changeLogType": "RANGER_POLICIES",
  "policyId": 640,
  "policyVersion": 3,
  "extraInfo": {
    "aclsExecuted": { "total": 0, "applied": 0, "failed": 0, "skipped": 0 },
    "policy": { "createTime": "2026-10-23 09:20:41", "updateTime": "2026-10-23 09:20:41" },
    "response": [
      { "code": 2002, "msg": "No change detected since last sync, grant not reapplied", "origin": "DBX", "count": 0 }
    ]
  }
}

ACCESS — Lake Formation (table SELECT grant)¶

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

{
  "eventType": "ACCESS",
  "evtTime": "2025-11-14T01:31:00.170Z",
  "timeTakenMs": 100,
  "status": "COMPLETED",
  "msg": "",
  "connectorType": "lakeformation",
  "connector": "Lakeformation-instance1",
  "changeLogId": 22576,
  "changeLogType": "RANGER_POLICIES",
  "policyId": 1,
  "policyVersion": 111,
  "policyName": "policyname",
  "policyType": "access",
  "policyLabel": "correlationId",
  "resourceType": "table",
  "resource": "975xxxxxx/us-west-1/db1/table1",
  "permission": "select",
  "action": "grant",
  "cmd": "Granted SELECT on table 975xxxxxx/us-west-1/db1/table1 for Role arn:aws:iam::975xxxxxx:role/lf-consumer-role-2",
  "cmdType": "api",
  "actor": "arn:aws:iam::975xxxxxx:role/lf-consumer-role-2",
  "actorType": "ROLE",
  "extraInfo": {
    "response": [
      { "code": 2001, "msg": "Resource synced; access grants applied", "origin": "AWS_LAKEFORMATION", "count": 1 }
    ]
  }
}

ACCESS — Databricks Unity Catalog (schema EXECUTE grant)¶

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

{
  "eventType": "ACCESS",
  "evtTime": "2025-11-14T01:31:00.170Z",
  "timeTakenMs": 50,
  "status": "COMPLETED",
  "msg": "",
  "connectorType": "databricks_unity_catalog",
  "connector": "databricks-unity-catalog-instance1",
  "changeLogId": 22576,
  "changeLogType": "RANGER_POLICIES",
  "policyId": 1,
  "policyVersion": 111,
  "policyName": "policyname",
  "policyType": "access",
  "policyLabel": "correlationId",
  "resourceType": "schema",
  "resource": "catalog1/schema1",
  "permission": "execute",
  "action": "grant",
  "cmd": "GRANT EXECUTE ON SCHEMA `catalog1`.`schema1` TO `account users`;",
  "cmdType": "sql",
  "actor": "account users",
  "actorType": "GROUP",
  "extraInfo": {
    "response": [
      { "code": 2001, "msg": "Resource synced; access grants applied", "origin": "DBX", "count": 1 }
    ]
  }
}

ACCESS — Databricks Unity Catalog (failed grant)¶

A failed grant on Databricks Unity Catalog. The failure is transient (5001), so the same grant may succeed if it is run again.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

{
  "eventType": "ACCESS",
  "evtTime": "2026-10-23T09:12:41.508Z",
  "status": "FAILED",
  "msg": "[SYSTEM_ERROR | retryable=true] INTERNAL_ERROR (State: XX000)",
  "connectorType": "databricks_unity_catalog",
  "connector": "dbx-uc-prod",
  "changeLogId": 48213,
  "changeLogType": "RANGER_POLICIES",
  "policyId": [812],
  "policyVersion": [7],
  "policyName": "finance-analysts-read",
  "resourceType": "table",
  "resource": "finance/ledger/transactions",
  "permission": "select",
  "action": "grant",
  "actor": "finance-analysts",
  "actorType": "GROUP",
  "extraInfo": {
    "response": [
      { "code": 5001, "msg": "Transient backend or infrastructure failure", "origin": "DBX", "serviceCode": "INTERNAL_ERROR", "count": 1 }
    ]
  }
}

A successful grant from the same policy carries 2001:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

{
  "eventType": "ACCESS",
  "status": "COMPLETED",
  "connector": "dbx-uc-prod",
  "changeLogId": 48213,
  "policyId": [812],
  "policyVersion": [7],
  "resource": "finance/ledger/accounts",
  "permission": "select",
  "action": "grant",
  "actor": "finance-analysts",
  "extraInfo": {
    "response": [
      { "code": 2001, "msg": "Resource synced; access grants applied", "origin": "DBX", "count": 1 }
    ]
  }
}

CHANGELOG — Lake Formation¶

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

{
  "eventType": "CHANGELOG",
  "evtTime": "2025-11-14T01:31:00.170Z",
  "timeTakenMs": 100,
  "status": "SKIPPED",
  "msg": "skipped because of this",
  "connectorType": "lakeformation",
  "connector": "Lakeformation-instance1",
  "changeLogId": 22576,
  "changeLogType": "RANGER_POLICIES",
  "extraInfo": {
    "policies": [
      {
        "id": "1",
        "version": "3"
      },
      {
        "id": "2",
        "version": "3"
      }
    ]
  }
}

LOADER — service resource loader¶

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

{
  "eventType": "LOADER",
  "evtTime": "2025-11-14T01:31:00.170Z",
  "timeTakenMs": 100,
  "status": "COMPLETED",
  "msg": "Resource loader completed",
  "connectorType": "lakeformation",
  "connector": "Lakeformation-instance1",
  "changeLogId": 22576,
  "changeLogType": "SERVICE_RESOURCES",
  "loaderType": "LOAD_SERVICE_RESOURCES",
  "triggerFrom": "SCHEDULED",
  "extraInfo": {
    "resources": {
      "catalog": {
        "found": 110,
        "added": 11,
        "updated": 12,
        "deleted": 12
      },
      "database": {
        "found": 110,
        "added": 11,
        "updated": 12,
        "deleted": 12
      }
    },
    "totalTimeTakenMs": 100,
    "startTime": "2025-11-14 01:31:00",
    "endTime": "2025-11-14 01:31:00"
  }
}

A successful loader run has no response[].

LOADER — failed resource load¶

A resource load that failed because the backend was unavailable. The code is 5001, so the next load may succeed.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

{
  "eventType": "LOADER",
  "evtTime": "2026-10-23T08:00:12.114Z",
  "status": "FAILED",
  "msg": "[HTTP_503 | retryable=true] Service unavailable",
  "connectorType": "databricks_unity_catalog",
  "connector": "dbx-uc-prod",
  "changeLogId": 48190,
  "changeLogType": "SERVICE_RESOURCES",
  "loaderType": "LOAD_SERVICE_RESOURCES",
  "triggerFrom": "SCHEDULED",
  "extraInfo": {
    "response": [
      { "code": 5001, "msg": "Transient backend or infrastructure failure", "origin": "DBX", "serviceCode": "HTTP_503", "count": 1 }
    ],
    "startTime": "2026-10-23 07:58:40",
    "endTime": "2026-10-23 08:00:12"
  }
}

ON_DEMAND — grants partially applied¶

One requested resource whose grants partly failed. response sits beside output, not inside it.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

{
  "eventType": "ON_DEMAND",
  "evtTime": "2026-10-23T09:20:05.731Z",
  "status": "FAILED",
  "msg": "Grants partially applied; some grants failed",
  "connectorType": "databricks_unity_catalog",
  "connector": "dbx-uc-prod",
  "changeLogId": 48230,
  "ondemandTaskId": 9127,
  "extraInfo": {
    "response": [
      { "code": 2001, "msg": "Resource synced; access grants applied", "origin": "DBX", "count": 3 },
      { "code": 4503, "msg": "Grantee principal not found in the target service", "origin": "DBX", "serviceCode": "PRINCIPAL_DOES_NOT_EXIST.PRINCIPAL_DOES_NOT_EXIST", "count": 1 },
      { "code": 5001, "msg": "Transient backend or infrastructure failure", "origin": "DBX", "serviceCode": "INTERNAL_ERROR", "count": 1 }
    ],
    "output": {
      "aclsExecuted": { "total": 5, "applied": 3, "failed": 2, "skipped": 0 }
    }
  }
}

ON_DEMAND — resource not found¶

A request for a table that does not exist in the source. The status is FAILED, but the code is in the EXPECTED range: there is nothing to fix or retry.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

{
  "eventType": "ON_DEMAND",
  "status": "FAILED",
  "msg": "Resource not found in source; nothing to apply",
  "connector": "dbx-uc-prod",
  "changeLogId": 48231,
  "ondemandTaskId": 9128,
  "extraInfo": {
    "response": [
      { "code": 1006, "msg": "Resource not found in source; nothing to apply", "origin": "DBX", "count": 1 }
    ]
  }
}

PROGRESS¶

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

{
  "eventType": "PROGRESS",
  "evtTime": "2025-11-14T01:31:00.170Z",
  "timeTakenMs": 100,
  "status": "PROCESSING",
  "msg": "",
  "connectorType": "lakeformation",
  "connector": "Lakeformation-instance1",
  "changeLogId": 22576,
  "changeLogType": "RANGER_POLICIES",
  "extraInfo": {
    "progress": {
      "total": 200,
      "sinceLastReport": 100
    }
  }
}

Response codes¶

extraInfo.response[] lists an event's outcomes. Each entry carries a stable numeric code, so you can act on an event without parsing its msg. ACCESS, POLICY_RESPONSE, and ON_DEMAND events always carry it; a LOADER event carries it only when its load failed, and a TEMPLATE_UPDATE_RESPONSE event only when a table failed.

Other changes in 9.2.48.1¶

No top-level field was added, removed, or renamed, and PolicySync applies grants as before. The other changes:

• New event type TEMPLATE_UPDATE_RESPONSE (Databricks Unity Catalog): one summary per changed row-filter template, after its tables are re-applied. A consumer or an Amazon SNS filter policy that lists event types must add it to receive it. See Audits of a template update.
• Template on ACCESS events: the ACCESS events of a template-based row filter carry extraInfo.udf_template (name, version, updateTime).
• extraInfo.response[] is new on ACCESS, POLICY_RESPONSE, ON_DEMAND, and failed LOADER events. Each entry has code, msg, origin, serviceCode, and count. The code's name and category are not in the event; look them up in the tables on this page.
• Policy times: for an added or updated policy in a RANGER_POLICIES changelog, POLICY_RESPONSE carries extraInfo.policy = {createTime, updateTime}. Compare updateTime with evtTime to see how long the change took to apply. Both are yyyy-MM-dd HH:mm:ss in the payload; Apache Solr and Privacera Portal show evtTime as ISO 8601.
• Code in the failure text: the failure text in the ACCESS, POLICY_RESPONSE, and LOADER msg, and in failedReasons, can start with a bracketed code, for example [SYSTEM_ERROR | retryable=true]. On LOADER it is the backend's code when there is one, for example [HTTP_503 | retryable=true]. It is for people reading the audit; code should read response[].

• Normalized failure text: ARNs, email addresses, IPv4 addresses, request IDs, and quoted or dotted names such as database.table are replaced with ?, and the text is cut to 512 characters. This applies to:

  • AWS Lake Formation: the ACCESS msg and the error message in its extraInfo, and the POLICY_RESPONSE msg and failedReasons. The AWS error code is kept, and is also in response[].serviceCode.
  • Every connector: the msg of a failed LOADER event, and output.errorDetails.serviceError on ON_DEMAND (see Why the outcome failed).

  A name with none of these shapes, such as a single-word table name, is kept, so treat the text as sensitive.

Moving from the single error code¶

Each old value becomes one or more entries in extraInfo.response[]. Branch on each entry's code.

ON_DEMAND output.errorCode:

Template-based row filter (Databricks Unity Catalog):

The response entry¶

1
2
3
4
5
6
7

{
  "code": 5001,
  "msg": "Transient backend or infrastructure failure",
  "origin": "DBX",
  "serviceCode": "08S01",
  "count": 1
}

Every field except serviceCode is always present.

Code ranges¶

The range of code gives its category, the way an HTTP status class does. The category names in this table are the ones the code tables on this page use; they are not fields of the event.

Only a code from 5000 to 5999 is worth retrying. It means that running the same operation again later may succeed; it does not mean that PolicySync retries it.

PARTIAL describes an event's overall outcome, never one entry. A policy where some grants applied and some failed is a POLICY_RESPONSE with status GRANT_PARTIALLY_APPLIED; an ON_DEMAND event reports it as FAILED with msg Grants partially applied; some grants failed. In both cases response[] lists each outcome as its own entry.

RESOURCE_NOT_FOUND has two numbers. It is 4501 (PERMANENT) when a grant or revoke targets a missing resource, and 1006 (EXPECTED) when a resource is missing while resources are loaded, for example because the table was dropped; nothing was applied. Each number has its own msg, but branch on code, not on the name or the text.

Origin¶

Every other outcome, success included, names the backend service. Other connectors report their connector type in uppercase, with each run of characters other than letters and digits replaced by _.

Code messages¶

The msg of each code that can appear in response[]. The wording can change between releases; branch on code.

Backend error codes (serviceCode)¶

When a grant, revoke, or resource load fails, serviceCode keeps the backend's own error code unchanged, and PolicySync maps it to a code.

• Branch on code, not on serviceCode. The lists below are common values, not a complete set.
• The same serviceCode can map to a different code on a grant or revoke than on a load; the tables say which.
• A serviceCode PolicySync does not recognize maps to 4502 on a grant or revoke, and 4505 on a load.
• A resource that an on-demand request names but the source does not have is 1006, with no serviceCode.

Databricks Unity Catalog and Databricks SQL use the same rules; origin is DBX or DBX_SQL. serviceCode is one of:

• A Databricks error condition, such as TABLE_OR_VIEW_NOT_FOUND, or a SQLState: grants, revokes, and loads that run SQL. Unity Catalog loads columns and foreign tables with SQL; Databricks SQL loads everything with SQL.
• HTTP_<status>: Unity Catalog loads of catalogs, schemas, and tables, which use the REST API, and SQL statements whose HTTP request Databricks rejected.

A compound condition such as SCHEMA_DOES_NOT_EXIST.RESOURCE_DOES_NOT_EXIST is mapped on whichever part PolicySync recognizes.

Some conditions look transient but need a fix, so they map to 4502 on a grant or revoke and 4505 on a load: DELTA_CONCURRENT_TRANSACTION, and any condition ending in .CHANGE_TYPE_COLUMN. An 08S01 or 40001 that the JDBC driver derived from the message text, rather than received from Databricks, is not transient either.

AWS Lake Formation — serviceCode is the AWS error code (for example EntityNotFoundException) or HTTP_<status>.

Response codes by event type¶

Each table below lists every code its event type can carry.

• Entries are sorted by count, highest first. Do not rely on the order of entries with the same count.
• An event lists at most ten entries. When there are more, the retryable (5xxx) entries are kept first, then the highest counts.
• A FAILED event can carry only EXPECTED entries, for example an AWS Lake Formation revoke of a permission that was already gone (1005), or an on-demand request for a resource that does not exist (1006). An alert built on status should also check the code's range.

ACCESS codes¶

A grant skipped because the grantee owns the resource (1004) has no ACCESS event; it is counted on the policy's POLICY_RESPONSE.

POLICY_RESPONSE codes¶

Each entry counts the policy's ACL operations, or owner skips, that had that outcome. The failure codes are the same as on the policy's failed ACCESS events.

The event status comes from the policy's ACL counts, aclsExecuted.applied and aclsExecuted.failed:

How the entries add up:

• While a policy has ten distinct outcomes or fewer, the counts add up to aclsExecuted.total plus ownerIgnore.count. Beyond ten, entries are left out as described in Response codes by event type, so the counts add up to less.
• There is no policy-level retry flag. To find what to retry, follow Link a failure to its ACCESS audits.

ON_DEMAND codes¶

An ON_DEMAND event's entries come from three sources (the Source column):

• ACL operations: a resource that reached grant application lists the outcomes of the on-demand task's ACL operations, grouped as on POLICY_RESPONSE. They cover the whole task, so every changed resource in the request lists the same entries. A resource whose outcome is RESOURCE_DELETED also lists 2004.
• Resource: any other resource lists its own outcome, one entry with count 1.
• Resource load: when the load failed, every resource in the request also lists the load failure's code.

The event status:

• COMPLETED when the resource's outcome is a success (2001–2004) and no ACL operation of the on-demand task failed.
• FAILED otherwise. A partial grant has msg Grants partially applied; some grants failed, and a resource not in the source has 1006.
• Failed ACL operations count for the whole task: when one fails, every resource in the request that reached grant application is FAILED, even if its own grants applied. A resource that did not change or was not found keeps its own outcome.

For how each outcome is decided, see Outcome codes.

output.lfForward is unchanged. AWS Table-Level Federation adds it when it forwards an on-demand sync to AWS Lake Formation, and names the reason LF_SYNC_FORWARD_FAILED when the forwarded task was not created. That reason has the number 4506 in the code registry, but it is never a response[] entry and does not change the resource's outcome.

LOADER codes¶

A LOADER event lists a code only when the load failed (status FAILED) and the connector classified the failure. The connectors that classify failures are Databricks Unity Catalog, Databricks SQL, and AWS Lake Formation, for the loaders that read the target service: resources, permissions, principals, and tags.

Template-based row filter (Databricks Unity Catalog)¶

When a template-based row filter cannot be applied, the failed ACCESS event, the policy's POLICY_RESPONSE, and an ON_DEMAND event for the table carry a code from 4001 to 4014, with origin PRIVACERA.

• DDL_FAILED (4002) and UNDECLARED_COLUMN (4011) come from Databricks rejecting a statement. They carry the Databricks error condition as serviceCode.
• A transient Databricks failure is 5001 SYSTEM_ERROR instead, with origin DBX.

For the list of codes, see Codes in the PolicySync audits. For causes and fixes, see Errors from the connector.

Limitations of response codes¶

• On ON_DEMAND, a resource that reached grant application lists the ACL outcomes of the whole on-demand task, not only its own. When one request changes several resources, a transient failure on one of them gives each of them a 5001 entry and makes each of them FAILED. To find the resource that failed, read the ACCESS events with the same ondemandTaskId.
• When a whole resource load stops because a catalog or schema is not found, the failed LOADER event, or every ON_DEMAND event of an on-demand request, can report 1006 RESOURCE_NOT_FOUND, which is in the EXPECTED range. Check status as well as the code.
• When an on-demand task fails before it reaches the target service, the entry can name the target service as its origin.

Link a failure to its ACCESS audits¶

POLICY_RESPONSE and ON_DEMAND events summarize many ACL operations. Each ACL operation also has its own ACCESS event, which names the resource, the permission, the principal, and the statement. To see which grants failed and which applied, find the ACCESS events behind the summary.

Fields that link the events¶

A changeLogId is unique only within one connector instance, so always match connector together with changeLogId.

A TEMPLATE_UPDATE_RESPONSE carries connector, changeLogId, and changeLogType (TEMPLATE_UDF_REAPPLY). Its failed tables are the FAILED ACCESS events with the same connector and changeLogId whose extraInfo.udf_template.name is the summary's template (the same run can apply other templates too); see Find the failed tables.

From a POLICY_RESPONSE¶

1. Note the event's connector, changeLogId, policyId, and policyVersion.
2. Find the ACCESS events with the same connector and changeLogId whose policyId list contains that policyId. When several Ranger policies give the same grant, the ACCESS event lists all of them; the version at the same position in policyVersion is the version that was applied.
3. Split them by outcome:
   • Failures: status FAILED. Each one's response[0].code and serviceCode match one of the failure entries in the POLICY_RESPONSE.
   • Successes: status COMPLETED with code 2001.
   • Skips: status SKIPPED with code 1003.
4. Retry only the ACCESS events whose code is from 5000 to 5999. Fix the policy, the principal, or the resource for the others.

An owner skip (1004) has no ACCESS event; it is counted in the POLICY_RESPONSE ownerIgnore.

In the example events, the POLICY_RESPONSE for policy 812 version 7 on changelog 48213 has a 5001 entry with count 1. The ACCESS event on finance/ledger/transactions with the same connector, changeLogId, and policyId carries that 5001, and is the grant to retry. The ACCESS event on finance/ledger/accounts carries 2001 and is one of the four that applied.

From an ON_DEMAND event¶

1. Note the event's connector and ondemandTaskId.
2. Find the ACCESS events with the same connector and ondemandTaskId. Each one names its resource and carries its own code.
3. Split and act on them as for a POLICY_RESPONSE.

The ACL outcomes on an ON_DEMAND event cover the whole on-demand task; see Limitations. The ACCESS events show which resource each outcome belongs to.

An ON_DEMAND event whose resource did not reach grant application, for example 1006, 2002, 2003, or 4505, has no ACCESS events.

From a LOADER event¶

A failed load applies no grants, so it has no ACCESS events. Its code tells you whether the next load may succeed (5001) or the configuration needs a fix. When the resource load of an on-demand request fails, every ON_DEMAND event of the request, with the same ondemandTaskId, lists the load failure's code.