Catalog reference migration limitations

When you upgrade Red Hat Edge Manager from a previous version, the automatic database migration converts label-based catalog references to catalogItemRef fields. In certain scenarios, the migration cannot convert a reference and the catalog association is lost.

Table 1. Catalog reference migration limitations
Scenario Behavior during migration Impact Manual remediation

Catalog item was deleted before upgrade

The migration process finds label references to a catalog item that no longer exists. The labels are ignored because there is no valid CatalogItem resource to resolve.

The device or fleet loses its catalog association. The operating system image or application continues to run from the previously resolved OCI image, but it is no longer tracked as a catalog deployment.

Re-create the catalog item in the catalog. Then apply a catalogItemRef field to the affected device or fleet specification that points to the re-created catalog item and version.

Channel was removed from the catalog item before upgrade

The migration process finds a channel label value that does not match any channel defined in the target CatalogItem version entries. The channel reference cannot be migrated.

The catalogItemRef might be created without the channel sub-field, or the migration might skip the reference entirely if channel validation is required.

Apply a catalogItemRef field to the affected device or fleet specification. Omit the channel sub-field if the channel no longer exists, or specify an updated channel value that matches a current channel in the catalog item.

Label data fails validation against the catalogItemRef model

The migration process attempts to convert the label values to a catalogItemRef field but the data fails validation. Examples include a nonexistent catalog name, an invalid version format, or a catalog item name that does not match any existing resource.

The labels are ignored and the catalog association is lost. The device or fleet retains its current running state but is no longer tracked as a catalog deployment.

Verify the correct catalog name, item name, and version by listing the available catalog items with flightctl get catalogitems --catalog <catalog_name>. Then apply a catalogItemRef field with the correct values.

Labels were manually modified to invalid values

The migration process finds labels with values that were manually edited to something the catalog system does not recognize. The invalid labels are ignored.

The catalog association is lost. The device or fleet continues to run its current configuration but without a catalog reference.

Identify the correct catalog, item, and version for the intended deployment. Apply a catalogItemRef field to the device or fleet specification with the correct values.