What this error means
For every symbol, ERC takes the library nickname from the symbol's
library identifier (the Device in Device:R) and tries to resolve it
through your symbol library tables. Three different failures report
under this one check, each with its own runtime message:
- The nickname is not in the global or project library table at all (or its row is disabled): "The current configuration does not include the symbol library 'X'".
- The table has the nickname, but the file its path points to did not load: "The symbol library 'X' was not found at '/the/resolved/path'".
- The library loads, but contains no symbol with that name: "Symbol 'Y' not found in symbol library 'X'".
The schematic still renders because every .kicad_sch file embeds a
cached copy of each symbol it uses; the check compares your library
configuration against that cache. A symbol with no cached copy is
skipped entirely, and while any of these warnings stands the companion
lib_symbol_mismatch check cannot run for that symbol — KiCad cannot
diff against a library it cannot load.
Common causes
1. The project came from another machine and its libraries didn't
A git clone, a coworker's zip, a CI runner. Symbol library tables
are per-machine configuration, so unless the project carries its own
sym-lib-table file, libraries set up on the original machine are
unknown on this one.
2. You upgraded KiCad to a new major version
Each major version keeps its own global symbol library table and its
own versioned path variable (KICAD9_SYMBOL_DIR, KICAD10_SYMBOL_DIR).
Hand-added libraries are not carried into the new table, and paths
written against the old version's variable stop resolving.
3. The library file moved or was renamed on disk
The table row is fine; the .kicad_sym it points to is gone. This
is the "was not found at" variant, and the message prints the exact
path KiCad tried.
4. The symbol was renamed or deleted inside the library
The library loads, but nothing in it matches the symbol's name — it was renamed in the library after being placed, or the nickname now points at a different file. This is the "not found in symbol library" variant.
How to fix it
Add the library to a symbol library table
- Open Preferences → Manage Symbol Libraries.
- Pick the Global Libraries tab, or Project Specific Libraries if the library should travel with this project.
- Add a row whose nickname is exactly the one in the warning, with the path to the `.kicad_sym` file.
- Re-run ERC (Inspect → Electrical Rules Checker).
Use when: The library exists but this machine's configuration has never heard of it — the "current configuration does not include" variant, and the 80% case.
Fix the path in the row KiCad already has
- Read the path out of the warning; that is where KiCad looked.
- In Preferences → Manage Symbol Libraries, correct the row's path — or fix the path variable it uses under Preferences → Configure Paths.
- Re-run ERC.
Use when: The "was not found at" variant: the table knows the library but the file is no longer where the row says.
Re-point the symbols to a library you still have
- Open Tools → Edit Symbol Library Links… (KiCad 10 names it Bulk Edit Symbol Library Links…).
- Map the orphaned library identifiers onto a configured library.
- Re-run ERC.
Use when: The old library is gone for good and its symbols live on only as cached copies inside the schematic. This swaps their identity to a library that exists instead of resurrecting one that doesn't.
When it’s safe to exclude
This is a configuration warning, not a connectivity error — the netlist and the board are built from the cached copies and are unaffected. For an archived project you will never edit again, downgrading the severity in Schematic Setup → Electrical Rules → Violation Severity is a defensible way to keep old designs opening clean.
For anything still being edited, fix the configuration instead. While
the warning stands, lib_symbol_mismatch silently skips those symbols,
so upstream library changes stop being flagged, and you cannot place
fresh copies of the symbol or update it from the library.
Gotchas
- One missing library produces one warning for every symbol placed from it. Two hundred warnings can mean one absent row in the library table.
- The check reads the cached
lib_symbolssection of the schematic file. A symbol without a cached copy is skipped silently, so this check passing is not proof the configuration is complete. - Being invisible to ERC also means being invisible to the symbol chooser: until the table row exists, you cannot place new symbols from that library either.
Minimal reproduction
Two-minute version: rename one of your libraries' nicknames in Preferences → Manage Symbol Libraries, reopen the schematic, and run ERC. Every symbol from that library reports:
[lib_symbol_issues]: The current configuration does not include the symbol library 'repro'
; warning
The checked-in file data/erc/samples/lib_symbol_issues.kicad_sch
reproduces this with a single embedded symbol whose library nickname
repro is deliberately absent from any library table. Here the missing
library is the point, not an artifact, and it is the only violation in
the report. Adding a sym-lib-table with a repro row pointing at a
matching .kicad_sym file drops the violation count to zero — fix #1
in miniature.
Related errors
- Symbol doesn't match copy in library (reference page coming soon)
- Footprint link issue (reference page coming soon)
FAQ
My schematic opens and renders fine — why should I care about this warning?
The schematic renders from symbol copies cached inside the file, so nothing looks wrong. The cost is forward-looking: KiCad cannot check those symbols against the library, update them when it changes, or offer the library for new placements. One row in Preferences → Manage Symbol Libraries removes all of those limitations.
I moved my project to a new PC and now ERC warns about every symbol. Where did my libraries go?
Symbol library tables are per-machine settings, not part of the project. Either add the libraries on the new machine under Preferences → Manage Symbol Libraries, or put them and a project-specific table next to the project so the configuration travels with it.
After upgrading KiCad, all my own libraries show this warning. Do I have to add them again?
Yes, once per major version. Each major release keeps a separate global symbol library table, and library paths written against a versioned variable like KICAD9_SYMBOL_DIR do not resolve under the next version's variable. Re-add your personal libraries, or repoint the rows at paths that survive upgrades.