Update Troubleshooting

Handling Common Update Issues

This section summarizes how to detect and resolve common problems that may occur during or after an update.

Liquibase Changelog Locks On The Admin Database

During an update, XDM may run database migrations using Liquibase. If a previous migration was interrupted, Liquibase may have left a lock in the changelog lock table. If Liquibase cannot obtain its changelog lock, new migrations cannot start and the update may fail and may prevent XDM from starting or updating correctly.

Symptoms:

  • Errors like Could not acquire change log lock. Currently locked by …​ during migration.

  • XDM services fail to start or stay in an error state.

Detecting Liquibase Changelog Locks

  • Look for errors in the core logs like:

    Could not acquire change log lock. Currently locked by <server_name> since <timestamp>.

  • Check the Liquibase lock tables in the admin database:

    • database_changelog_lock.

    • databasechangeloglock.

The row with ID = 1 usually indicates whether the lock is active.

Resolution summary:

  • Connect to the admin database with a SQL client.

  • Reset the lock entries in the Liquibase lock tables, for example:

    UPDATE "public".database_changelog_lock
SET LOCKED = FALSE, LOCKEDBY = NULL, LOCKGRANTED = NULL
WHERE ID = 1;

UPDATE "public".databasechangeloglock
SET LOCKED = FALSE, LOCKEDBY = NULL, LOCKGRANTED = NULL
WHERE ID = 1;

  • Restart the XDM Core services (or the corresponding pods/containers).

  • Check the logs again to ensure that migrations run successfully.

Session Deserialization Problems After Updates

If users still have active HTTP sessions when an update replaces internal libraries, session deserialization can fail after the update. This can lead to exceptions such as InvalidClassException for classes used inside the session objects.

Symptoms:

  • Stack traces containing:

    java.io.InvalidClassException local class incompatible

  • Errors during login or when accessing the UI after an update.

Root cause:

  • Older session data stored in the admin database (for example in the spring_session table) is no longer compatible with the updated libraries.

Resolution summary:

  • Ideally: wait until all sessions expire automatically (by idle timeout) before starting the update. You can check this in the session table in the admin database.

  • If this is not possible:

    • Identify the session table (typically spring_session in the admin database).

    • Mark the sessions as expired or remove them (for example by updating the expired column or deleting rows).

    • Restart the XDM services so that users obtain fresh sessions.

  • After clearing sessions, all users must log in again.

If old sessions are incompatible with the updated version, you may see exceptions such as InvalidClassException when XDM tries to deserialize session data.

  • Check the core server logs:

    • Kubernetes

    • Docker

    kubectl logs <core-pod-name> --namespace <NAMESPACE>
    docker compose logs core-server

  • Look for:

    • java.io.InvalidClassException

    • ConversionFailedException or SerializationFailedException when reading session data.

These errors indicate that session objects stored in the admin database were created by a previous version and cannot be deserialized by the new version.

When And How To Clear Session Storage

If you encounter session deserialization errors after an update:

  1. If possible, wait until all old sessions expire automatically based on the configured idle timeout and session lifetime.

  2. If the errors persist or you cannot wait:

    • Connect to the admin PostgreSQL database.

    • Identify the table used for sessions (typically spring_session).

    • Either:

      • Mark all sessions as expired (for example by setting the expired column to true), or

      • Delete the affected rows entirely.

        This will invalidate all current sessions, and users must log in again.

  3. Restart the core service so that new sessions are created with the updated version.

For detailed examples of how to manipulate the session table, refer to the session troubleshooting article in the Knowledge Base.