Plugin Catalog Status main - redhat-developer/rhdh-plugin-export-overlays GitHub Wiki
Plugin Catalog Index Status β main
Build date: 2026-10-16 14:09 UTC
Source: main @ df088d5
Backstage: 1.54.9 | RHDH: 2.2
Catalog index branch: catalog-index-main
Workflow run: View run
Summary
| Tier | Total | Passed | Outdated | BS Mismatch | Failed | Latest Catalog Index Image | Last Successful Publish |
|---|---|---|---|---|---|---|---|
| Supported | 69 | 69 | 0 | 0 | 0 | quay.io/rhdh-community/plugin-catalog-index:2.2-bs_1.54.9-df088d5 | df088d5 |
| Community | 37 | 37 | 0 | 0 | 0 | ghcr.io/redhat-developer/rhdh-plugin-export-overlays/plugin-catalog-index:2.2-bs_1.54.9-df088d5 | df088d5 |
Supported Catalog
Passed (69)
Community Catalog
Passed (37)
Troubleshooting
Common issues reported on the status page and how to resolve them.
Build failed β catalog index validation
What it means: Step 5 (validateCatalogIndex.py) found a blocking issue. The catalog-index-{branch} git branch may still be updated for debugging, but OCI publish is skipped when generation fails (--validate-mode gate in the generate workflow).
Always fails (every branch):
- Image not found in registry β no exact tag and no fallback.
- Missing, empty, or unreadable
io.backstage.dynamic-packageson any plugin image. dynamic-plugins.default.yamldoes not list every package fromdefault.packages.yaml.- DPDY
package:is a tag, not a digest β the tag points at the manifest list.
Fails only on release-* (--strict):
- Plugin marked as outdated (version fallback).
- Backstage version mismatch.
- Plugin version regressed vs the previous published catalog index (see below).
strict: falseon a release line opts only this check out.
What to do: Fix the underlying issue (publish the plugin, restore the annotation, bump the workspace). On main, fallback, mismatch, and version-regression issues are warnings and the catalog still publishes. Those warnings appear on the generated status page.
Plugin version regressed vs previous release
What it means: The supported catalog resolved a plugin to an older npm/plugin version than the last published catalog index for this RHDH version β even though the OCI image exists and installed cleanly. On main the status page lists these under Version regression; on release-* the build fails unless strict: false was used for an emergency rollback.
Common cause: Metadata was bumped before the new plugin image was published; the pipeline fell back to an older tag and nobody rebuilt the index after publish.
What to do:
- Publish the correct plugin version for the requested tag.
- Re-run catalog index generation (on
release-*,--strictenforces this automatically). - On
main, this is a warning only until the nextrelease-*build.
Missing io.backstage.dynamic-packages annotation
What it means: The OCI image exists but lacks the io.backstage.dynamic-packages manifest annotation required for dynamic plugin installation. This always fails the build on every branch and tier.
What to do: Re-export and publish the plugin with @red-hat-developer-hub/cli plugin package so the annotation is set. Verify with skopeo inspect --raw on the image manifest.
Backstage version mismatch
What it means: The plugin's workspace targets an older Backstage minor version than the one expected by the current branch. The plugin is still included in the catalog index: community (ghcr.io) builds use the workspace's actual Backstage version in the image tag so the image can resolve. The status page flags this as a warning so you can update the workspace when a compatible upstream version is available. On release-* branches with --strict, this fails the build instead.
Common cause: The upstream plugin repository has not yet released a version compatible with the latest Backstage version, or the workspace's source.json repo-ref points to an older tag.
What to do:
- Check if a newer tag or commit exists in the upstream repo that supports the required Backstage version.
- If a workspace update PR exists in the overlays, try commenting
/update-committo pull the latest compatible ref. - If no compatible version exists upstream, add a
backstage.jsonoverride in the workspace to pin the version.
Plugin marked as outdated
What it means: The exact requested image tag couldn't be found. Instead the latest published tag for the same Backstage/RHDH version line is being used as a fallback. The plugin is still included in the catalog index rather than being removed entirely. On main this is a warning; on release-* with --strict this fails the build and blocks OCI publish.
When this happens:
- The plugin version in metadata was bumped (e.g.,
1.2.0β1.3.0) but the export/publish workflow hasn't run yet for the new plugin version. - For example:
- The requested tag is
bs_1.49.4__1.3.0but onlybs_1.49.4__1.2.0is published β the older tag is used. - The requested tag is
1.11-0.5.2but only1.11-0.4.6and1.11-0.4.5are published, then1.11-0.4.6is used.
- The requested tag is
What to do:
- Check whether the publish workflow has run successfully for this plugin.
- Trigger the export/publish workflow for the plugin to publish the plugin with the updated tag.
If this fallback also fails (no older tag exists), the plugin will instead appear as Image not found in registry.
Image not found in registry
What it means: No OCI image exists in the container registry for any tag matching the plugin's Backstage or RHDH version. The pipeline has no image to use β not even an older one to fall back to (see Outdated) β so the plugin is excluded from the catalog index entirely. This always fails the build on every branch.
When this happens:
- A plugin is newly onboarded for the specified backstage/RHDH version and the export/publish workflow has never run for it yet.
- For example, a plugin may have been updated from
bs_1.45.3tobs_1.49.4and now expectsbs_1.49.4__1.2.0and it might not have been published yet as nobs_1.49.4_*tags exist yet. Even if a tag likebs_1.45.3__1.1.1exists, it will not be considered for the fallback.
What to do:
- Check whether the publish workflow has run successfully for this plugin.
- Trigger the export/publish workflow for the plugin to publish the plugin with the updated tag.
Image not found during catalog index generation
Note: This is the same "Image not found" error as above, but detected during the final Catalog Index Generation step rather than during Image Metadata Fetch. It serves as a redundancy check which normally should never happenβ if you see this, the image was likely deleted or became unavailable after the metadata fetch stage. Re-run the workflow to see if this persists, as it may be a transient registry issue. The resolution steps are the same as Image not found in registry.
Catalog index validation failed
Step 5 of the generation (scripts/validateCatalogIndex.py) checks the generated index
against the build metadata that produced it, without touching the network. A plugin whose
only failing stage is Catalog Index Validation was built and published fine β what
failed is the index's description of it.
Each finding is written as [rule-id] message. Run
python3 scripts/validateCatalogIndex.py --list-rules for the full set.
unresolved-image
The index ships this package, but its image was never resolved in the registry β the generator logged "Image not found in registry" and carried on. Anyone who enables the package fails at pull time.
Fix: publish the missing build (see Image not found in registry), or drop the package from the packages file so the index stops declaring it. Allowlisting is the wrong answer here: it ships a package that cannot be pulled.
unknown-image
The index references an image with no plugin_builds/ entry, so the index and the build
metadata disagree. Usually a stale catalog-index/ committed without the matching
plugin_builds/, or a rename that updated one and not the other.
Fix: re-run the generation so both are produced from the same inputs.
digest-mismatch
A digest-pinned reference does not match the digest plugin_builds/ recorded β the two
files describe different builds of the same plugin.
Fix: re-run the generation. If it persists, the index was edited by hand.
registry-not-allowed
A selected plugin's OCI reference uses the wrong registry for its support tier.
support: community must use the exact --community-registry base; every other
support tier must use the exact --registry base. The policy checks the DPDY,
plugin_builds/, index.json, and selected Package entities, and always fails
update-index.sh even when --validate-mode is report or off.
Fix: correct the Package entity's support tier or republish the image to its
expected registry, then regenerate the index. Pass --community-registry for
community-tier packages when they use a different base; if omitted, community uses
--registry. This finding cannot be allowlisted.
duplicate-ref
The same package reference appears twice in dynamic-plugins.default.yaml. The later
entry silently shadows the earlier one's pluginConfig, so whichever configuration you
expected may not be the one that applies.
Fix: remove the duplicate entry.
ref-form
A plugins[].package value is not an oci:// reference. Generated indexes should never produce this; it means the file was hand-edited or a generator step wrote a malformed value.
index-ref-mismatch
index.json and dynamic-plugins.default.yaml point at different digests for one
package, so the Extensions UI and the installer would disagree about which build is
current.
Fix: re-run the generation.
missing-annotation
The OCI image exists but lacks a usable io.backstage.dynamic-packages annotation:
missing, empty, or present but not readable Base64/JSON (RHIDP-16251 / RHDHBUGS-2530).
This always fails the build.
Fix: re-export and publish the plugin with @red-hat-developer-hub/cli plugin package
so the annotation is set. Verify with skopeo inspect on the image manifest.
dpdy-missing-package
A package listed in default.packages.yaml is not in dynamic-plugins.default.yaml.
Matching is by npm name / derived image name, so swapping one package for another of the
same count still fails.
Fix: restore the missing package in metadata so DPDY generation includes it, or
remove it from default.packages.yaml if it should not ship.
not-digest-pinned
A plugins[].package value is an oci:// tag (:2.1.0--4.2.5) rather than a
child-manifest digest (@sha256:β¦). Tags resolve to the OCI index / manifest list,
which does not carry io.backstage.dynamic-packages, so install-dynamic-plugins
fails with InstallException: No plugins found (RHDHBUGS-3815). This always
fails the build on every branch.
Typical cause: the plugin image was not in the registry yet when the catalog index was generated, so Step 4 never rewrote the tag copied from metadata.
Fix: publish the plugin image, then re-run catalog index generation. Do not allowlist a missing digest β a tag-only DPDY entry is not installable.
Warnings that do not fail the stage
fallback-tag means the requested build was missing and an older tag was substituted β
the index ships a stale build. backstage-version-mismatch means the workspace targets
an older Backstage minor than this branch. version-regression means the plugin version
is lower than the previous published catalog index (RHIDP-16252); the status page
renders these from stages.validate.warnings.
index-missing-entry means a resolved package
is missing from index.json, so the Extensions UI will not list it.
None of these fail the plugin's validate stage, but --strict (release branches)
fails the build on them.
Auto-generated by the catalog index generation pipeline