ClickHouse DB::Exception: User account expired

The "DB::Exception: User account expired" error in ClickHouse occurs when a user attempts to log in after their account's valid_until date has passed. The USER_EXPIRED error code means the server recognizes the user but refuses the connection because the account's validity period has ended.

Impact

The expired user is completely locked out of ClickHouse. All connection attempts are rejected regardless of whether the credentials are correct. Any application or service using the expired account will lose access to the database, which can disrupt data pipelines, dashboards, and scheduled jobs.

Common Causes

1. The user account was created with a VALID UNTIL clause and that date has passed
2. A temporary or contractor account was intentionally set to expire
3. Security policies enforce periodic account expiration, and the account was not renewed
4. The account was created with a short validity period for testing and was accidentally used in production
5. Time zone differences between the server clock and the administrator's expectation of when the account expires

Troubleshooting and Resolution Steps

1. Confirm the account has expired:

   SHOW CREATE USER my_user;
   

   Look for the VALID UNTIL clause and compare it to the current server time.

2. Check the current server time:

   SELECT now();
   

   Ensure the server clock is accurate. An incorrect clock could cause premature expiration.

3. Extend the account's validity:

   ALTER USER my_user VALID UNTIL '2027-12-31';
   

4. Remove the expiration entirely:

   ALTER USER my_user VALID UNTIL 'infinity';
   

5. If the account should remain expired, create a new account:

   CREATE USER new_user IDENTIFIED BY 'password' VALID UNTIL '2027-06-30';
   GRANT SELECT ON my_database.* TO new_user;
   

6. Review expiration policies:

   • If your organization enforces account expiration, establish a renewal process that extends valid accounts before they expire.

Best Practices

• Track account expiration dates in a centralized system and set up alerts before accounts expire.
• Use VALID UNTIL for temporary, contractor, or external user accounts that should have a defined lifetime.
• For service accounts that need persistent access, either omit the VALID UNTIL clause or set it far in the future with a documented renewal process.
• Synchronize server clocks using NTP to avoid unexpected expiration due to time drift.
• Document your organization's account expiration policy and renewal procedure.

Frequently Asked Questions

Q: Can I set a user to never expire?
A: Yes. Either omit the VALID UNTIL clause when creating the user, or set it to 'infinity'. Users without a VALID UNTIL clause do not expire.

Q: Does the expiration time use the server's time zone?
A: Yes. The VALID UNTIL timestamp is evaluated against the server's local time. Ensure you account for the server's time zone when setting expiration dates.

Q: Can I see all users that are about to expire?
A: You can query the system.users table to check the valid_until column and compare it to the current time to find accounts nearing expiration.

Q: What happens to active sessions when a user account expires?
A: Existing active sessions typically continue until they end naturally. The expiration is enforced at login time, so new connections will be rejected but running queries are not immediately terminated.