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
| Fact | Value |
|---|---|
| Issue type | unresolved-catalog-reference |
| Rule id in SARIF output | fallow/unresolved-catalog-reference |
| Command | fallow dead-code |
| Default severity | error |
Config key in rules | unresolved-catalog-references |
| Filter option | --unresolved-catalog-references |
Fixable with fallow fix | No |
| Opt-in | No |
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.yamluses its own catalog.