pcb_via_trace_clearance_error

Diagnostic signature

pcb_via_trace_clearance_error

A Design Rule Check (DRC) error indicating that the distance between a PCB trace and a via is less than the required minimum clearance.

What it means

This diagnostic represents a design rule violation within the printed circuit board (PCB) layout where the physical distance between a routed trace and a via drops below the required minimum clearance threshold. In the tscircuit ecosystem, this conflict is manifested as a `pcb_via_trace_clearance_error` object appended to the intermediate Circuit JSON representation. The diagnostic object embeds specific metadata to assist in debugging, including the `pcb_via_id` of the via, the `pcb_trace_id` of the trace, the `minimum_clearance` mandated by the rules, and the `actual_clearance` that was measured during validation.

Why it happens

During the evaluation of the PCB layout, the toolchain's validation engine computes the shortest geometric distance between the outer boundary of a via (typically its annular ring) and the edges of adjacent trace segments. If this calculated proximity is less than the global or net-specific clearance design rules, the engine detects a spatial conflict. To report this violation, it appends a `pcb_via_trace_clearance_error` element to the generated Circuit JSON array, ensuring downstream rendering tools or design rule checkers can display visual error indicators over the overlapping or dangerously close geometries.

Minimal reproduction

import { Board, Trace, Via } from "@tscircuit/core";

export const ClearanceViolationBoard = () => (
  <Board width="20mm" height="20mm">
    <Via 
      name="via1" 
      center={{ x: "0mm", y: "0mm" }} 
      outerDiameter="1mm" 
      holeDiameter="0.5mm" 
      fromLayer="top" 
      toLayer="bottom" 
    />
    <Trace
      path={[
        { x: "-5mm", y: "0.2mm" },
        { x: "5mm", y: "0.2mm" }
      ]}
      thickness="0.2mm"
      layer="top"
    />
  </Board>
);

How to fix it

Reroute the trace or move the via to ensure sufficient physical distance exists between their boundaries, satisfying the PCB clearance constraints.

```TSX
import { Board, Trace, Via } from "@tscircuit/core";

export const ClearanceViolationBoard = () => (
  <Board width="20mm" height="20mm">
    <Via 
      name="via1" 
      center={{ x: "0mm", y: "0mm" }} 
      outerDiameter="1mm" 
      holeDiameter="0.5mm" 
      fromLayer="top" 
      toLayer="bottom" 
    />
    <Trace
      path={[
        { x: "-5mm", y: "2mm" },
        { x: "5mm", y: "2mm" }
      ]}
      thickness="0.2mm"
      layer="top"
    />
  </Board>
);
```

Step 1

• Examine the diagnostic object to identify the offending trace and via using the `pcb_trace_id` and `pcb_via_id` fields.

Step 2

• Compare the `actual_clearance` against the `minimum_clearance` reported in the error to determine how far the elements must be moved.

Step 3

• Adjust the layout coordinates of the trace's `path` to create a wider detour around the via.

Step 4

• Alternatively, relocate the via's `center` coordinates to an area with adequate routing space.

Upstream references

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

circuit-json source: pcb_via_trace_clearance_error.ts