Skip to content
Fallow home
All docs pages

Docs home

Unresolved catalog references

What an unresolved-catalog-reference finding of fallow dead-code means, why it matters and how to fix it.

What it reports

package.json references a catalog that does not declare the package.

Dependencies explains how fallow finds it.

Why it matters

A workspace package.json declares a dependency with the catalog: or catalog:<name> protocol, but the catalog has no entry for that package. The package manager install will fail until the catalog is fixed. To fix: add the package to the named catalog, switch the reference to a different catalog that does declare it, or remove the reference and pin a hardcoded version. Scope: the detector scans dependencies, devDependencies, peerDependencies, and optionalDependencies in every workspace package.json, plus the pnpm override values in pnpm-workspace.yaml overrides (skipped when packageManager names a pnpm version that ignores it: pnpm before 10.5.1, or pnpm 10 or earlier when the root package.json declares non-empty pnpm.overrides or resolutions), root package.json pnpm.overrides (skipped when packageManager names pnpm 11 or later, because pnpm 11 does not read it), and root package.json resolutions (read only when packageManager names pnpm 10 or earlier), using pnpm-workspace.yaml catalogs when present and Bun root package.json catalogs otherwise. See also: fallow/unused-catalog-entry (the inverse: catalog entries no consumer references).

Example

packages/app/package.json declares "old-react": "catalog:react17", but catalogs.react17 in the catalog source does not declare old-react. The package manager install will fail.

Fix

If available_in_catalogs is non-empty, change the reference to one of those catalogs (e.g. catalog:react18). Otherwise add the package to the named catalog in the catalog source, or remove the catalog reference and pin a hardcoded version. For staged migrations where the catalog edit lands separately, add the (package, catalog, consumer) triple to ignoreCatalogReferences in your fallow config.

Facts

FactValue
Issue typeunresolved-catalog-reference
Rule id in SARIF outputfallow/unresolved-catalog-reference
Commandfallow dead-code
Default severityerror
Config key in rulesunresolved-catalog-references
Filter option--unresolved-catalog-references
Fixable with fallow fixNo
Opt-inNo

When to keep the code

  • When the catalog change comes in a later commit, add the package, the catalog and the consumer to ignoreCatalogReferences.

Notes

  • A reference is not unresolved when a pnpm override without a version selector replaces the package, because pnpm applies overrides first.
  • A nested pnpm project with its own pnpm-workspace.yaml uses its own catalog.