license-checker "UNKNOWN" license (missing license field) in CI

By Kaveh Alemi·Latchkey

license-checker could not determine a license for a package because its package.json has no license field and no parseable LICENSE file, so it labels the entry UNKNOWN. A strict --onlyAllow then fails because UNKNOWN is not on the list.

What this error means

The summary or per-package output shows a dependency with license "UNKNOWN". With --onlyAllow set, the run exits 1 because UNKNOWN never appears in an allow list.

└─ my-internal-pkg@0.0.1
   ├─ licenses: UNKNOWN
   └─ path: node_modules/my-internal-pkg
error: Found license defects.

Common causes

The package omits a license field

Some internal or abandoned packages publish without a license in package.json and without a LICENSE file, leaving license-checker nothing to detect.

The license is non-SPDX free text

A package uses a custom string that license-checker cannot map to a known identifier, so it falls back to UNKNOWN.

How to fix it

Add a license field to the offending package

1. If you own the package, add a valid SPDX license to its package.json.
2. Republish or, for a workspace package, commit the fix so the next install carries it.
3. Re-run license-checker to confirm the entry is no longer UNKNOWN.

{
  "name": "my-internal-pkg",
  "version": "0.0.1",
  "license": "MIT"
}

Clear a vetted UNKNOWN with an override

For a third-party package you cannot change, exclude it by name once legal has confirmed its actual license.

npx license-checker --onlyAllow "MIT;ISC;Apache-2.0" \
  --excludePackages "my-internal-pkg@0.0.1"

How to prevent it

• Require a valid SPDX license field in internal package templates.
• Track UNKNOWN entries in review so they are resolved, not silently allowed.
• Prefer maintained dependencies that publish clear license metadata.

Frequently asked questions

Related guides

References

• GitHub Actions documentation