What this error means
For every symbol whose Footprint field is non-empty, ERC takes the text
before the colon as a library nickname (Resistor_SMD in
Resistor_SMD:R_0603_1608Metric) and resolves it through your footprint
library tables — the global one plus the project's fp-lib-table if it
has one. Three lookups can fail, each with its own runtime message:
- The nickname is in neither table, or the field has no nickname at all: "The current configuration does not include the footprint library 'X'".
- The table has the nickname but its row is switched off: "The footprint library 'X' is not enabled in the current configuration".
- The library resolves but has no footprint by that name: "Footprint 'Y' not found in library 'X'".
A field that cannot be parsed as a footprint identifier at all reports "'X' is not a valid footprint identifier" instead. Symbols with an empty Footprint field are skipped — this check validates assignments that exist, it does not hunt for missing ones.
Common causes
1. The footprint library isn't configured on this machine
The project arrived by git clone, zip, or a new computer, and its
Footprint fields name a personal library only the original machine's
table knew about. Footprint library tables are per-machine unless
the project ships its own fp-lib-table file.
2. You moved up a major KiCad version
Global footprint library tables are kept per major version, and rows
written against KICAD9_FOOTPRINT_DIR don't resolve under KiCad
10's variable. There is also a step effect: the check only exists
since 9.0, so an 8.x project with stale Footprint fields warns for
the first time the day you open it in 9.
3. The footprint was renamed or deleted in its library
The library row is fine; the named footprint is gone. Renaming in the Footprint Editor does not update the Footprint fields of symbols that referenced the old name, and a typo in a hand-edited field lands in the same place.
4. The Footprint field has no library nickname
A field like SOIC-8 instead of Package_SO:SOIC-8... — typical of
imported designs and hand-typed fields. The nickname KiCad extracts
is empty, which is why the warning names a library called ''.
How to fix it
Add or fix the library row in the footprint library table
- Open Preferences → Manage Footprint Libraries.
- Pick the Global Libraries tab, or Project Specific Libraries if the library should travel with the project.
- Add a row whose nickname exactly matches the name in the warning, pointing at the `.pretty` directory — or fix the existing row's path or re-tick its Active checkbox.
- Re-run ERC (Inspect → Electrical Rules Checker).
Use when: The "does not include" and "not enabled" variants: the library exists on disk, the table just has no working row for it. The 80% case.
Re-assign the footprint
- Run Tools → Assign Footprints… to work through the whole schematic, or double-click the symbol and edit its Footprint field with the library browser.
- Pick the footprint from a configured library, then re-run ERC.
Use when: The "not found in library" and bare-name cases: the field's content, not the table, is wrong. Browsing instead of typing is the point — it can only produce identifiers that resolve.
Ship a project fp-lib-table for CI and other machines
- Add the library on the Project Specific Libraries tab with a `${KIPRJMOD}`-relative path.
- Commit the resulting `fp-lib-table` file and the `.pretty` directory with the project.
Use when: The schematic is checked by kicad-cli in CI or opened on machines you don't control. A fresh container has no global footprint library table, so without a project table every assignment warns there.
When it’s safe to exclude
Not while the board still gets updated. The same unresolved link means Update PCB from Schematic cannot fetch the footprint ("Cannot add U1 (footprint 'nolib:TEST' not found)."), so the problem resurfaces as a hard error at layout time; this warning is just the earliest place it shows up.
Downgrading the severity in Schematic Setup → Electrical Rules → Violation Severity is defensible for archived projects whose boards are final — the netlist itself is unaffected. Excluding single markers (right-click → Exclude) is rarely worth it here: one missing library row produces a marker per symbol, and you'd be excluding them by the dozen.
Gotchas
- The warning count scales with symbol count, not problem count. Eighty violations naming the same library is one bad table row, not eighty jobs.
- Headless runs have their own configuration.
kicad-cli sch ercin a fresh container sees no global footprint library table, so CI can report dozens of these on a schematic that checks clean in your GUI. A committed projectfp-lib-tablefixes both sides. - In KiCad 9, and in 10.0 releases through 10.0.3, a mismatch against the symbol's footprint filters is also filed under this check; newer 10.0 releases report it under "Assigned footprint doesn't match footprint filters" instead.
- Passing says little: symbols with an empty Footprint field are not checked, so a clean report does not mean every part has a footprint.
Version notes
- KiCad 9.0: Check introduced in this release.
Minimal reproduction
Two-minute version: open any symbol's properties, type a made-up name
into the Footprint field (nolib:TEST), and run ERC. The symbol
reports:
[footprint_link_issues]: The current configuration does not include the footprint library 'nolib'
; warning
The checked-in file data/erc/samples/footprint_link_issues.kicad_sch
reproduces this with one embedded symbol whose Footprint field is
nolib:TEST; its pin carries a no-connect flag, so the report holds
the target warning plus a single lib_symbol_issues warning about the
embedded repro symbol library — an artifact of the self-contained
file, not part of this error. Dropping an fp-lib-table with a nolib
row next to the file clears the violation: fix #1 in miniature.
Related errors
- Library symbol issue
- Assigned footprint doesn't match footprint filters
- Different footprint assigned in another unit of the symbol
FAQ
ERC was clean on my old PC — why does a fresh install warn that the configuration does not include the library?
The global footprint library table is machine configuration, not project data, and a new install only knows the stock libraries. Re-add your personal libraries under Preferences → Manage Footprint Libraries with the exact nicknames the warnings print, or commit a project fp-lib-table so the setup travels with the project.
Why does the warning name an empty library ''?
The symbol's Footprint field has no library nickname — something
like SOIC-8 instead of Package_SO:SOIC-8_3.9x4.9mm_P1.27mm.
KiCad parses everything before the colon as the library name and
finds nothing. Re-assign the footprint through the library browser
to get a fully qualified identifier.
kicad-cli ERC in CI reports footprint library warnings my desktop doesn't. Why?
The container runs with its own KiCad configuration, which has no
global footprint library table or personal libraries. Commit an
fp-lib-table next to the project with ${KIPRJMOD}-relative paths
and the CI run resolves the same libraries your desktop does.
Is this warning about symbol libraries or footprint libraries?
Footprint libraries — the check only reads the Footprint field. Problems resolving the symbol itself report as "Library symbol issue", so one symbol can carry both warnings and need two separate fixes.