What this error means
ERC scans every piece of text the schematic displays — symbol fields, text
and text boxes (including ones embedded in library symbols), label fields,
sheet fields and sheet pins, and the drawing sheet's title block — expands
environment variables, resolves text variables, and then looks at what is
actually shown. If the displayed text still contains anything of the form
${...}, the item is flagged.
So the check does not care why the variable failed to resolve. An
undefined project variable, a misspelled built-in like ${REVISON}, a
cross-reference to a symbol that no longer exists, or an unset environment
variable all end the same way: the literal ${...} survives to the display
text and ERC reports it. The same literal survives to plots, which is why
the default severity is error — an excluded violation becomes ${BOARD_REV}
printed on your PDF.
Project text variables are defined per project and stored in the
.kicad_pro file, not in the schematic. Built-in variables (${REVISION},
${SHEETNAME}, ${U1:VALUE}, ...) resolve from the title block, sheet, or
the referenced symbol — and some only resolve in certain contexts.
Common causes
1. The variable is not defined in this project
The name inside ${...} does not match any row in Schematic Setup →
Project → Text Variables and is not a built-in. Typos are the usual
form: variable names must match exactly, and ${BOARD_REV} with a
table entry BOARDREV is just another undefined name.
2. The schematic is separated from its project file
Definitions live in the .kicad_pro. A .kicad_sch shared as a single
file, a project whose .kicad_pro never made it into version control,
or a kicad-cli run against a schematic without its project file next
to it has no text variables at all — every ${...} in it errors at
once, even though the same schematic was clean on the machine it came
from.
3. A cross-reference points at a symbol that is gone
Field references like ${U9:VALUE} resolve through the reference
designator. Delete U9, or reannotate so it becomes U12, and the text
keeps saying ${U9:VALUE} — now unresolvable.
How to fix it
Define the variable, or fix its name
- Open File → Schematic Setup… → Project → Text Variables (same path in KiCad 9 and 10).
- Add a row with the exact variable name and its value — or correct the name in the flagged text to match an existing row or built-in.
- Re-run ERC (Inspect → Electrical Rules Checker).
Use when: The variable is one you meant to use. One table serves the whole project, schematic and board both.
Reunite the schematic with its project file
- Keep the .kicad_pro next to the .kicad_sch: commit it to version control and include it when sending files.
- For CLI runs, point kicad-cli at the schematic inside its project directory so the .kicad_pro is picked up.
Use when: The schematic was clean elsewhere and erupted in unresolved-variable errors after being moved, cloned, or mailed on its own.
Repair stale cross-references
- Double-click the violation to jump to the flagged text.
- Update ${REFDES:FIELD} to the symbol's current reference designator, or delete the reference if the symbol is gone for good.
Use when: The flagged text names a specific symbol. Reannotation and deletions do not update cross-references for you.
When it’s safe to exclude
Rarely — the unresolved ${...} prints literally on plotted output, so
excluding the violation usually means shipping a PDF whose title block says
${BOARD_REV}. Fixing it costs one row in a dialog.
The one honest case: text that is supposed to show the syntax, like a
schematic note explaining ${VARIABLE} usage to your team. Exclude that
marker (right-click → Exclude violation) rather than downgrading the whole
check in Schematic Setup → Electrical Rules → Violation Severity, which
would also silence the real placeholders this check exists to catch.
Gotchas
- The marker tells you an item failed, not which variable. In the GUI,
double-click the violation to jump to the item; in a report file, the
@(x, y)line quotes the offending text. - The Board Editor runs the same check as a DRC violation with the same name, reading the same project table. Defining the variable in Schematic Setup fixes both sides; there is no second table to maintain.
Minimal reproduction
Place a text item containing a variable nobody defined — Rev: ${BOARD_REV} — and run ERC (Inspect → Electrical Rules Checker). That is
the whole reproduction; no symbols or wires needed. The report says:
[unresolved_variable]: Unresolved text variable
; error
@(101.60 mm, 101.60 mm): Graphic Text 'Rev: ${BOARD_REV}'
The checked-in file data/erc/samples/unresolved_variable.kicad_sch
reproduces this with a single text item and nothing else — because it
embeds no symbols, it produces exactly one violation and no
missing-library warnings. Creating a unresolved_variable.kicad_pro next
to it with "text_variables": { "BOARD_REV": "A" } drops the error count
to zero, which is the Schematic Setup fix in miniature.
Related errors
FAQ
ERC is full of 'Unresolved text variable' errors with no details — how do I find which variable it means?
Double-click each violation in the ERC dialog to jump to the flagged item, or read the ERC report file: the line under each violation gives the item and its text, such as Graphic Text 'Rev: ${BOARD_REV}'. If no schematic item is highlighted, check the title block — drawing-sheet text is scanned too.
The variable is defined in my other project — why is it unresolved here?
Project text variables are stored in each project's .kicad_pro file, not globally. Every project that uses ${YOURVAR} needs its own row in Schematic Setup → Project → Text Variables. The same applies to a schematic opened without its project file: no .kicad_pro, no definitions.
Why does my board show 'Unresolved text variable ${REF}' after upgrading KiCad?
That is the board-side DRC version of this check. KiCad's built-in for a footprint's reference designator is ${REFERENCE}; ${REF} is not among the defined variables, so footprint text carried forward from old projects reports as unresolved. Edit the footprint text to use ${REFERENCE} and the violation clears.
Sources
- Check implementation — ERC_TESTER::TestTextVars, eeschema/erc/erc.cpp at KiCad 10.0.3
- Check implementation at KiCad 9.0.9.1 (same logic)
- KiCad 10 Schematic Editor manual — list of ERC checks
- KiCad 10 Schematic Editor manual — Text Variables in Schematic Setup
- KiCad 10 Schematic Editor manual — text variables and built-in names