ClickHouse DB::Exception: Unknown row policy

The "DB::Exception: Unknown row policy" error in ClickHouse occurs when a statement references a row policy that does not exist on the server. The UNKNOWN_ROW_POLICY error code is raised when ClickHouse cannot find a matching row policy definition for the specified name and table combination.

Impact

The operation referencing the missing row policy fails. This can prevent administrators from modifying or dropping a policy, and it blocks any provisioning scripts that depend on the policy being present. Existing queries are not directly affected unless the system is trying to apply a policy that no longer exists, which could impact data access patterns.

Common Causes

The row policy was never created on the target table
A typo in the policy name or the table name it applies to
The policy was dropped but is still referenced in scripts or configuration
Migration between clusters did not include row policy definitions
The policy was created on a different table than expected (row policies are scoped to specific tables)
Confusion between policy names on different tables

Troubleshooting and Resolution Steps

List all existing row policies:
```
SHOW ROW POLICIES;
```
Check if the expected policy name and table combination exist.
View details for a specific table's policies:
```
SHOW ROW POLICIES ON my_database.my_table;
```

Create the missing row policy:

CREATE ROW POLICY my_policy ON my_database.my_table
  FOR SELECT USING department = 'engineering'
  TO my_role;

If migrating, export the policy definition from the source:
```
SHOW CREATE ROW POLICY my_policy ON my_database.my_table;
```
Execute the resulting statement on the target server.
Verify the table exists:
- Row policies are tied to specific tables. If the table was dropped or renamed, the policy reference becomes invalid:
```
SHOW TABLES FROM my_database;
```
Check for name and scope mismatches:
- A row policy named filter_by_region on table_a is distinct from one with the same name on table_b. Ensure you reference both the policy name and the correct table.

Best Practices

Use descriptive names for row policies that include the table and purpose (e.g., restrict_orders_by_region).
Include row policy creation in your migration and deployment scripts alongside table creation.
Audit row policies regularly using SHOW ROW POLICIES to ensure they align with current security requirements.
In clustered environments, use ON CLUSTER when creating row policies to ensure consistency across nodes.
Document which roles and users each row policy targets to simplify troubleshooting.

Frequently Asked Questions

Q: Are row policies scoped to a specific table?
A: Yes. Each row policy is associated with a specific table. You must specify the table when creating, altering, or dropping a row policy.

Q: Can I have multiple row policies on the same table?
A: Yes. Multiple row policies can coexist on a single table. They can target different users or roles and are combined using OR logic by default (a row is visible if any applicable policy allows it) or AND logic if configured with AS RESTRICTIVE.

Q: What happens if I drop a table that has row policies?
A: The row policies are dropped along with the table. If you recreate the table, you need to recreate the policies as well.

Q: How do I see which users are affected by a row policy?
A: Use SHOW CREATE ROW POLICY policy_name ON table_name to see the full definition, including which users and roles the policy applies to via its TO clause.