Keycloak upgrade Troubleshooting

Keycloak upgrade common problems

Below you’ll find some errors that you can encounter while upgrading Keycloak. Those errors are not related to an invalid database states and might not need a full rollback.

Troubleshoot story: Keycloak is running, but I can’t access the Management Service Portal

Are you seeing an error log like the below?

yyyy-MM-dd HH:mm:ss,SSS ERROR [org.keycloak.services] (executor-thread-25) KC-SERVICES0093: Invalid parameter value for: scope
yyyy-MM-dd HH:mm:ss,SSS WARN  [org.keycloak.events] (executor-thread-25) type=LOGIN_ERROR, realmId=axual, clientId=self-service, userId=null, ipAddress=<ip_address>, error=invalid_request, response_type=code, redirect_uri=https://<platform_hostname>/dashboard, response_mode=query
bash

If so, you’ll need to configure the optional scopes the KC client (self-service) can use. To do that, access Keycloak’s Admin Console and go to the Clients page using the sidebar

Keycloak Configure Clients Sidebar

  1. In the clients listing, select self-service and go to the Client Scopes tab:

    Keycloak Self-Service Client Scopes

  2. Make sure you have the profile assigned to the self-service client, as shown below:

    Keycloak Self-Service Client Profile Scope Assigned
If Metrics Exposer is enabled, make sure to have its scope (metrics-exposer) assigned as an optional client scope.

Troubleshoot story: Keycloak pod is restarting and a see a database migration error in the logs

Make sure to run the equivalent script if you are seeing an error like the below:

yyyy-MM-dd HH:mm:ss,SSS ERROR [org.keycloak.quarkus.runtime.cli.ExecutionExceptionHandler] (main) ERROR: Failed to start server in (production) mode
yyyy-MM-dd HH:mm:ss,SSS ERROR [org.keycloak.quarkus.runtime.cli.ExecutionExceptionHandler] (main) ERROR: Failed to update database
yyyy-MM-dd HH:mm:ss,SSS ERROR [org.keycloak.quarkus.runtime.cli.ExecutionExceptionHandler] (main) ERROR: liquibase.exception.MigrationFailedException: Migration failed for change set META-INF/jpa-changelog-12.0.0.xml::12.1.0-add-realm-localization-table::keycloak failed. Error: You have an error in your SQL syntax; check the manual that corresponds to your MariaDB server version for the right syntax to use near 'clob' [Failed SQL: CREATE TABLE keycloak.REALM_LOCALIZATIONS (REALM_ID varchar(255) not null, LOCALE varchar(255) not null, TEXTS clob not null, primary key (REALM_ID, LOCALE))]
bash

The log will show which migration is failing (in this case, 12.1.0-add-realm-localization-table) and you can run it manually if needed. The script contains the migration names making it possible to identify and run a single migration instead of the whole script.