PCB Via Clearance Error

Diagnostic signature

pcb_via_clearance_error

A design rule check error indicating that two vias on a printed circuit board are placed closer than the required minimum clearance distance.

What it means

The `pcb_via_clearance_error` diagnostic indicates that two plated through-holes (vias) on a printed circuit board have been placed closer together than the allowed minimum clearance distance. This clearance boundary is enforced in `tscircuit` to ensure that physical limitations of manufacturing are respected. When via geometries—such as their outer annular rings—are separated by an inadequate amount of space, it increases the risk of short circuits, solder bridging during manufacturing, or structural weaknesses in the substrate caused by drills being placed too close together. The constraint applies regardless of whether the vias belong to the same electrical net or different nets.

Why it happens

This diagnostic is emitted by the `@tscircuit/checks` design rule check library when it processes the generated `circuit-json` payload. It specifically triggers when functions like `checkSameNetViaSpacing` or `checkDifferentNetViaSpacing` detect that the measured distance between the geometries of two `<via />` elements is less than the specified `minClearance` value. This violation commonly occurs when manual layout constraints—such as overlapping `pcbX` and `pcbY` coordinate assignments—are applied incorrectly. It can also happen when an autorouter or trace layout system fails to correctly observe design limits, placing vias in close proximity.

Minimal reproduction

export default () => (
  <board width="10mm" height="10mm">
    <via 
      fromLayer="top" 
      toLayer="bottom" 
      outerDiameter="0.8mm" 
      holeDiameter="0.4mm" 
      pcbX={0} 
      pcbY={0} 
    />
    <via 
      fromLayer="top" 
      toLayer="bottom" 
      outerDiameter="0.8mm" 
      holeDiameter="0.4mm" 
      pcbX={0.2} 
      pcbY={0} 
    />
  </board>
)

How to fix it

Increase the distance between the violating vias by adjusting their placement coordinates until they satisfy the minimum clearance rules.

```tsx
export default () => (
  <board width="10mm" height="10mm">
    <via 
      fromLayer="top" 
      toLayer="bottom" 
      outerDiameter="0.8mm" 
      holeDiameter="0.4mm" 
      pcbX={0} 
      pcbY={0} 
    />
    <via 
      fromLayer="top" 
      toLayer="bottom" 
      outerDiameter="0.8mm" 
      holeDiameter="0.4mm" 
      pcbX={2} 
      pcbY={0} 
    />
  </board>
)
```

Step 1

• Identify the two vias involved in the clearance violation by inspecting their coordinates or grouping assignments on the board.

Step 2

• Modify the pcbX or pcbY properties on one or both <via /> components to increase the physical distance between them.

Step 3

• Ensure the calculated edge-to-edge separation between their outer diameters meets or exceeds the necessary manufacturing spacing.

Upstream references

circuit-json [email protected] — PcbViaClearanceError — retrieved 2026-08-11

circuit-json/src/pcb/pcb_via_clearance_error.ts at main - GitHub