keystone — Errors

Errors — keystone — branch stable/2026.2

Branch stable/2026.2 @ e6dc5ae079e6 — repository https://opendev.org/openstack/keystone — analysed on 2026-10-28

1. How an exception becomes an HTTP response

Unlike Placement, Keystone has a single central translation:

• every subclass of keystone.exception.Error that has an HTTP code is registered automatically in KEYSTONE_API_EXCEPTIONS (keystone/exception.py:27-60);
• each one is attached to the Flask handler _handle_keystone_exception (keystone/server/flask/application.py:126-173, registered at keystone/server/flask/application.py:202-203).

The handler:

1. Special cases:
   • InsufficientAuthMethods → 401 with an auth receipt (keystone/receipt/handlers.py);
   • OAuth2Error → RFC 6749 body (keystone/oauth2/handlers.py);
   • RedirectRequired → 302 (WebSSO).
2. Logging:
   • Unauthorized → WARNING "Authorization failed. <exception> from <remote_addr>", with the client address;
   • NotFound → DEBUG;
   • any other error → LOG.exception (stack trace).
3. Body (status = the exception's code): json {"error": {"code": 404, "title": "Not Found", "message": "Could not find user: 6c3…"}} The message is translated according to Accept-Language (keystone/server/flask/application.py:113-123). For AuthPluginException (incomplete MFA, for example), error.identity lists the methods and their data.
4. 401 responses add WWW-Authenticate: Keystone uri="<public base URL>" (keystone/server/flask/application.py:170-172).

Exceptions that are not Keystone exceptions:

• TypeError becomes **400 ValidationError** (keystone/server/flask/application.py:176-183). This is what a client sees when it calls a member method on a collection path (REST API § 1).
• Any other exception (SQL error, LDAP error, bug) escapes Flask and goes to the WSGI server: a 500 without a Keystone body [inferred: PROPAGATE_EXCEPTIONS=True, keystone/server/flask/application.py:218-221].
• werkzeug exceptions (404 unknown route, 405 method not declared) get Flask's HTML body, not Keystone's JSON [inferred from Flask behaviour].

Message masking (SecurityError)

Unauthorized, Forbidden and UnexpectedError derive from SecurityError (keystone/exception.py:260-312). **The message passed at raise time is only shown if [DEFAULT]/insecure_debug = true.** Otherwise the client receives the class's generic template ("The request you have made requires authentication.", "You are not authorized to perform the requested action.", "An unexpected error prevented the server from fulfilling your request.").

Subclasses raised with named arguments (UserDisabled(user_id=…), AccountLocked(user_id=…), PasswordExpired(user_id=…), ForbiddenAction(action=…)) do show their template filled in, for example "The account is locked for user: 6c3….". Clients and operators can therefore tell the authentication failures apart, except bad credentials, which stay generic ("Invalid username or password" only with insecure_debug).

Database conflicts

@sql.handle_conflicts (34 driver methods) turns oslo.db's DBDuplicateEntry into **409 Conflict** "Duplicate entry found with name X at domain ID Y". The raw SQL is only logged at DEBUG (keystone/common/sql/core.py:567-610).

2. Statuses and situations that matter to clients

Traps for a client or a rewrite:

• A token that fails validation is a 404, not a 401, while a bad X-Auth-Token on any other call is a 401. keystonemiddleware relies on this distinction.
• **401 with a body that has an identity field**: incomplete MFA. The client must send the receipt back with the Openstack-Auth-Receipt header.
• Auth errors stay generic unless insecure_debug is set: a rewrite must keep this masking, or it leaks whether an account exists.

3. Errors that never reach the client

4. Complete catalogue (109 classes)

Generated from keystone.exception (code, title and template read on the class). The raise sites are the raise exception.X lines outside tests (689 in all; the first three are shown).

Source: reverse-spec-keystone/02-errors_stable-2026.2.md. The _rewrite/ and _inventory/ files are not published on the site.