ClickHouse DB::Exception: Unknown quota

The "DB::Exception: Unknown quota" error in ClickHouse occurs when a user or configuration references a quota profile that does not exist on the server. The UNKNOWN_QUOTA error code means ClickHouse looked up the named quota and could not find a matching definition.

Impact

The affected user's session or query may be rejected if the server cannot resolve the assigned quota. In some configurations, this can prevent the user from connecting at all. Operations that reference the missing quota -- such as ALTER USER ... QUOTA statements or user profile assignments -- will also fail.

Common Causes

A user account references a quota name that was never created
The quota was deleted or renamed but user assignments still point to the old name
A typo in the quota name within users.xml, SQL configuration, or profile settings
The quota was defined in an XML configuration file that was removed or not loaded
Replication or migration between ClickHouse clusters missed the quota definitions
Configuration files in users.d/ were not picked up due to incorrect file permissions or naming

Troubleshooting and Resolution Steps

List existing quotas:
```
SHOW QUOTAS;
```
Verify that the referenced quota name appears in the output.
Check which quota is assigned to the user:
```
SHOW CREATE USER my_user;
```
Look for the QUOTA clause and confirm the referenced name exists.

Create the missing quota:

CREATE QUOTA my_quota
  FOR INTERVAL 1 hour MAX queries = 1000, read_rows = 1000000
  TO my_user;

Fix the user assignment if the quota name was wrong:
```
ALTER USER my_user QUOTA correct_quota_name;
```

Check XML configuration:

If quotas are defined in users.xml or users.d/ files, verify the <quotas> section contains the expected entries:

<quotas>
  <my_quota>
    <interval>
      <duration>3600</duration>
      <queries>1000</queries>
    </interval>
  </my_quota>
</quotas>

Reload configuration if needed:
```
SYSTEM RELOAD CONFIG;
```

Best Practices

Define quotas before assigning them to users to avoid referencing nonexistent profiles.
Use consistent naming conventions for quotas to reduce the risk of typos.
Include quota definitions in your infrastructure-as-code or migration scripts so they are deployed alongside user accounts.
Periodically audit quota assignments with SHOW QUOTAS and SHOW CREATE USER to detect dangling references.
When renaming or removing quotas, update all user and role assignments first.

Frequently Asked Questions

Q: How do I see all quota assignments across users?
A: Query the system.quota_usage table or run SHOW CREATE USER for each user. The system.quotas table also shows all defined quotas.

Q: Can a user function without a quota?
A: Yes. Quotas are optional. If no quota is assigned, the user operates without resource consumption limits (beyond server-level settings).

Q: What happens if I delete a quota that is still assigned to users?
A: Those users will encounter the UNKNOWN_QUOTA error on their next connection or query. Always reassign or remove quota references before deleting a quota.

Q: Can I assign different quotas to the same user for different time intervals?
A: A single quota definition can contain multiple intervals (e.g., hourly and daily limits). Each interval is tracked independently within that quota.