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

  1. Open File → Schematic Setup… → Project → Text Variables (same path in KiCad 9 and 10).
  2. 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.
  3. 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

  1. Keep the .kicad_pro next to the .kicad_sch: commit it to version control and include it when sending files.
  2. 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

  1. Double-click the violation to jump to the flagged text.
  2. 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.

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