What this error means
Every symbol needs a unique reference designator: R1, C3, U2. Until
annotation assigns the number, the reference ends in ? (R?, U?), and
that is literally what this check tests: the GUI ERC dialog walks every
symbol in the schematic and reports the first one whose reference still has
no number. The report line is Item not annotated: U?, with a
(unit 2) suffix when a specific unit of a multi-unit symbol is the
offender.
The reference is how everything downstream identifies the part — netlist,
BOM, footprint assignment, PCB — so a U? has no identity, and two U?s
are indistinguishable. The ERC dialog itself warns "Schematic is not fully
annotated. ERC results will be incomplete." before running.
Common causes
1. Annotation was never run (auto-annotation is off)
With Automatically annotate symbols disabled (Preferences →
Schematic Editor → Editing Options), every placed symbol keeps its
? until you annotate manually. People coming from tutorials that
assume auto-annotation hit this on their first ERC run.
2. Annotation was cleared and not re-run
The Annotation tool's Clear Annotation button resets every
reference in scope back to ?. Clearing to renumber a schematic and
then getting pulled away before re-annotating leaves the schematic in
exactly this state.
How to fix it
Run the Annotation tool
- Open Tools → Annotate Schematic… (also the Annotate button in the top toolbar; the ERC dialog's warning banner links straight to it).
- Keep the defaults: scope Entire schematic, annotate only unannotated symbols.
- Click Annotate, then re-run ERC (Inspect → Electrical Rules Checker).
Use when: Always works, and never disturbs references that are already assigned unless you pick the reset option.
Turn auto-annotation on so it stops happening
- Open Preferences → Preferences… → Schematic Editor → Editing Options.
- Check Automatically annotate symbols.
Use when: Symbols you place from now on get a reference immediately. Ordering and starting-number rules live in Schematic Setup → Annotation.
Set a single reference by hand
- Select the symbol and press E (Edit Symbol Properties).
- Replace the ? in the Reference field with a number no other symbol uses.
Use when: One stray symbol on a schematic that is otherwise annotated the way you want, and you don't trust a bulk tool near it.
When it’s safe to exclude
Never. There is no legitimate schematic state in which a symbol should keep
a ? reference, and the fix is one dialog away. Excluding the violation
(right-click the marker → Exclude) hides it without making the symbol
usable: netlists, BOMs, and the PCB update will still see an anonymous
part. If the error annoys you, that is the tool politely insisting you
press one button.
Gotchas
- The GUI reports at most one unannotated symbol per ERC run — the check stops at the first hit. Ten unannotated symbols produce one violation, not ten. Annotate once and they all go away together, so this rarely matters in practice, but don't interpret "1 violation" as "1 symbol affected".
- Power symbols never show this error. KiCad annotates them internally
(they get hidden
#PWRreferences) before ERC runs. kicad-cli sch ercstays silent about unannotated symbols — see the callout at the top. The netlist and BOM exporters are the CLI commands that notice, and they only print a generic warning.
Minimal reproduction
GUI (2 minutes): place any symbol, make sure auto-annotation is off
(Preferences → Schematic Editor → Editing Options), so its reference reads
U?. Run Inspect → Electrical Rules Checker. The dialog banner says the
schematic is not fully annotated, and the violations list shows:
[unannotated]: Item not annotated: U?
The checked-in file data/erc/samples/unannotated.kicad_sch holds exactly
that schematic — one embedded symbol with reference U?. Running it
through kicad-cli sch erc --severity-all under KiCad 9.0.8 and 10.0.8
produces no [unannotated] violation; the only output is the
lib_symbol_issues warning that is an artifact of the self-contained
sample. That negative result is the point: the CLI never runs this check.
Related errors
- Duplicate reference designators
- Symbol has more units than are defined
- Units of same symbol have different values
FAQ
Why doesn't ERC flag my unannotated symbols when I run it from the command line?
Because the annotation check is not part of the ERC engine. The GUI
dialog runs it separately before the real checks and injects the
results, and kicad-cli sch erc only runs the engine. This is a known
gap for CI pipelines: a schematic full of R? symbols exits with zero
violations. kicad-cli sch export netlist does detect the condition,
but only as a generic warning line.
I annotated the schematic — why did the markers not disappear?
ERC markers are a snapshot; they are not live. Re-run ERC after annotating and the violation will not come back. If it does, check whether the Annotation tool's scope was limited to the current sheet or a selection while the offending symbol sits on another sheet.
Can KiCad annotate symbols automatically as I place them?
Yes. Enable Automatically annotate symbols in Preferences → Schematic Editor → Editing Options (there is also a toggle button in the left toolbar of the schematic editor). Ordering and numbering preferences for this live in Schematic Setup → Annotation.
Sources
- Check implementation — SCH_REFERENCE_LIST::CheckAnnotation, eeschema/sch_reference_list.cpp at KiCad 10.0.3
- GUI ERC dialog annotation pre-pass — eeschema/dialogs/dialog_erc.cpp at KiCad 10.0.3
- CLI ERC job (no annotation check) — eeschema/eeschema_jobs_handler.cpp at KiCad 10.0.3
- KiCad 10 Schematic Editor manual — Annotation tool
- KiCad 9 Schematic Editor manual — Electrical rules checking