What this error means

Bus aliases are saved in the .kicad_sch file that was open when the alias was created, not in the project file. ERC collects the alias definitions from every sheet file and compares any two that share a name. Member lists are sorted before comparison, so order never matters and identical copies on several sheets are fine. Same name with different member sets raises one error naming both files.

The check is severity error because the conflict does not resolve visibly. For connectivity, KiCad 9 keeps a single alias per name in a cache that each sheet file overwrites in load order, so the definition loaded last wins for the whole project. A bus label like {CTRL} can expand to a different set of nets than the sheet that defined CTRL expects, and nothing on the canvas shows which definition won.

Common causes

1. A reused or copied sheet file brought its own copy of the alias

Each sheet file carries the aliases created while it was open. Reuse a sheet from another project, or keep a duplicated sheet file around, and the project holds two definitions of the same name. They start identical, which ERC accepts, and conflict the first time one copy's member list is edited without the other.

2. The alias was added again from a different sheet

The Add button in Bus Alias Definitions attaches the new alias to the sheet you had open, and the "Alias name already in use" guard only rejects duplicates within that one sheet file. Add CTRL while a subsheet is open and you get a second CTRL in the subsheet's file, not an edit of the existing one.

How to fix it

Delete or align the duplicate in Bus Alias Definitions

  1. Open File → Schematic Setup → Project → Bus Alias Definitions (same path in KiCad 9 and 10).
  2. Find the rows sharing one name. Select each: the sheet file that owns it is shown below the alias list.
  3. Delete the stale row, or make the member lists identical, then click OK and re-run ERC.

Use when: Always — this is the only fix. Verified under 9.0.9: either deleting one definition or making the member lists match clears the error.

Check the files directly when the panel is ambiguous

  1. Search each .kicad_sch file in the project for `bus_alias` in a text editor and compare the member lists.
  2. Decide which definition is current, then fix or delete the others in the panel, leaving one definition per name.

Use when: Several sheets carry near-identical definitions and you cannot tell from the panel which one the design was drawn against.

When it’s safe to exclude

Never. The conflict means some sheets were drawn against a member list the netlister may not be using. Excluding the marker (right-click → Exclude) or downgrading the check in Schematic Setup → Electrical Rules → Violation Severity keeps that ambiguity in the design, and the fix is cheaper than the exclusion: delete one row in a dialog. KiCad 10 no longer warns about this at all, so clean a project up while a 9.x ERC still shows the error.

Gotchas

  • The violation has no position. The report prints no coordinates and the GUI marker lands at the sheet origin, because the conflict lives in two files' alias tables, not in anything you drew. Look in Schematic Setup, not on the canvas.
  • The dialog's duplicate-name guard only watches one sheet file at a time, which is why the second definition is always in a file you weren't looking at when you made it.
  • Identical duplicates never warn. Five sheets can each define DATA with the same members, in any order, and ERC stays quiet — until one copy gains a member.

Version notes

  • KiCad 10.0: KiCad 10 no longer reports this violation. The check's item definition still exists, but no code path raises it: 10.0 collects every sheet's aliases into one project-wide list and a name lookup returns the first definition found, so a conflicting copy is silently ignored. Verified empirically: the two-sheet repro that fails under 9.0.9 reports zero violations under 10.0.6. Clean up duplicates while a 9.x ERC still points at them.
Minimal reproduction

In the GUI: in a project with one hierarchical sheet, define alias CTRL with members EN CLK in Bus Alias Definitions while the root sheet is open. Enter the subsheet, open the panel again, add CTRL with members EN RST — the duplicate-name warning stays quiet because the new copy lands in the subsheet's file. Run ERC:

[bus_definition_conflict]: Bus alias CTRL has conflicting definitions on /work/bus_definition_conflict_sub.kicad_sch and /work/bus_definition_conflict.kicad_sch
    ; error

The checked-in pair data/erc/samples/bus_definition_conflict.kicad_sch (root, run ERC on this) and bus_definition_conflict_sub.kicad_sch reproduces this: the root defines CTRL as EN CLK, the subsheet as EN RST. The paths in the message are absolute, from the machine that ran ERC. The sample draws no symbols or wires at all, since the check reads alias tables rather than the canvas, so the target error is the only violation in the report. Editing the subsheet's members to EN CLK drops the report to zero violations; KiCad 10.0.6 reports zero on the conflicting pair too, because 10 no longer runs this check.

  • Net is graphically connected to a bus but not a bus member (reference page coming soon)
  • Buses are graphically connected but share no bus members (reference page coming soon)
  • More than one name given to this bus or net

FAQ

ERC says my bus alias has conflicting definitions, but I only defined it once. Is the message wrong?

The second definition is real; it lives in a sheet file you did not edit by hand, often one reused from another project. Open Schematic Setup → Project → Bus Alias Definitions and select each row with that name: the owning file is shown below the alias list. Delete the copy that is stale.

Do I have to define a bus alias on every sheet that uses it?

No. An alias defined in any sheet file of the hierarchy can be used in group bus labels on every sheet. Re-defining it per sheet is legal only while the member lists stay identical, and duplicating it is what sets this error up later.

My bus alias members changed by themselves. How did the definitions diverge?

KiCad 8.0.8 and 9.0.0 had a reported bug (GitLab issue #20040, closed February 2025) where creating a new alias in a hierarchical design overwrote another alias's members. Update to a current 9.x release, then repair the member lists in Bus Alias Definitions.

Sources