Skip to main content

Liquibase Snapshot Command Fails with Null Snapshot ID Error

Lora Griffin
Updated

Applies to

  • Liquibase Secure (Pro)

Conditions

  • Database: Oracle Database
  • Liquibase Version: 4.33.0 and earlier versions 
  • Command: liquibase snapshot 
  • Environment: Occurs when the database contains specific object name conflicts

 

Issue Summary

When running the liquibase snapshot command against an Oracle database, the command fails with an "UnexpectedLiquibaseException" indicating a null snapshot ID was found for a specific table. This prevents the snapshot from completing successfully and can block deployment pipelines.

Error Message

ERROR: Exception Details
ERROR: Exception Primary Class:  UnexpectedLiquibaseException
ERROR: Exception Primary Reason:  Found a null snapshotId for table <TABLE_NAME>
ERROR: Exception Primary Source:  Oracle Oracle Database 19c Enterprise Edition Release 19.0.0.0.0 - Production

liquibase.exception.UnexpectedLiquibaseException: Found a null snapshotId for table <TABLE_NAME>
    liquibase.serializer.core.yaml.YamlSnapshotSerializer.toMap(YamlSnapshotSerializer.java:61)
    liquibase.serializer.core.yaml.YamlSerializer.toMap(YamlSerializer.java:118)
    ...

 

In Liquibase 5.0 and later:

ERROR: Exception Primary Reason: Found a null snapshotId for table <TABLE_NAME>. To suppress this failure, set --fail-on-null-snapshot-id=false

 

Root Cause

This error occurs when there is a naming conflict in the Oracle database schema where multiple database objects share the same name. The most common scenarios include:

  1. Table and Materialized View with the same name - When both a table and a materialized view exist with identical names, especially if the materialized view has an "INVALID" status
  2. Table and Constraint with the same name - When a check constraint or other constraint is named identically to a table name
  3. Multiple objects of different types sharing the same identifier - This causes Liquibase's snapshot serialization process to encounter a null snapshot ID when attempting to uniquely identify objects

The null snapshot ID occurs because Liquibase cannot properly differentiate between these objects during the snapshot metadata collection process, leading to serialization failures.

 

Resolution

Step 1: Upgrade to Liquibase 5.0 or Later

This issue has been permanently resolved in Liquibase 5.0 (documented under bug fix DAT-20436). Upgrading to Liquibase 5.0 or later will automatically handle this scenario.

The release of Liquibase Secure 5.0 brings important changes. See: New Distribution Channels for Liquibase Secure 5.0

 

Step 2: Use the fail-on-null-snapshot-id parameter (Liquibase 5.0+)

After upgrading to Liquibase 5.0 or later, you can control whether the snapshot command fails when encountering objects with null snapshot IDs.

Default Behavior (Liquibase 5.0+): By default, --fail-on-null-snapshot-id=true, which maintains the existing behavior of failing when unparseable, unfindable, or reference objects are encountered.

To Allow Snapshot to Continue: Set the flag to false to suppress the failure and allow the snapshot to complete, skipping problematic objects:

Using CLI:

liquibase snapshot --fail-on-null-snapshot-id=false

 

Step 3: Identify Problematic Objects (Optional)

To identify which objects are causing the null snapshot ID issue, run the following diagnostic queries:

-- Check for objects with the same name
SELECT object_name, object_type, status 
FROM all_objects 
WHERE object_name = '<YOUR_TABLE_NAME>' 
  AND owner = '<YOUR_SCHEMA>';

-- Check for constraints with the same name
SELECT OWNER, CONSTRAINT_NAME, TABLE_NAME, CONSTRAINT_TYPE
FROM ALL_CONSTRAINTS
WHERE CONSTRAINT_NAME = '<YOUR_TABLE_NAME>';

-- Check for indexes with the same name
SELECT OWNER, INDEX_NAME, TABLE_NAME
FROM ALL_INDEXES
WHERE INDEX_NAME = '<YOUR_TABLE_NAME>';

 

Enable detailed logging to see which objects are being skipped:

liquibase snapshot --fail-on-null-snapshot-id=false --log-level=fine --log-file=snapshot.log

 

For Users Unable to Upgrade to 5.0

If you cannot immediately upgrade to version 5.0, please contact Liquibase Support for assistance. When contacting support, provide:

  • Your current Liquibase version
  • Complete log output with --log-level=fine enabled
  • Results from the diagnostic queries above

 

Related Articles

Related to

Related articles

Comments

0 comments

Article is closed for comments.