tscircuit: pcb_footprint_overlap_error

Diagnostic signature

pcb_footprint_overlap_error

In tscircuit and Circuit JSON, pcb_footprint_overlap_error is a PCB design rule violation emitted when physical footprint features—such as surface-mount pads, plated through-holes, non-plated holes, or keepouts—from distinct components collide or overlap on the board canvas.

What it means

The pcb_footprint_overlap_error diagnostic represents a physical collision between two or more footprint elements on the printed circuit board layout. In Circuit JSON, it is instantiated as a BaseCircuitJsonError subclass with error_type 'pcb_footprint_overlap_error'. The error payload links the offending primitive identifiers via fields such as pcb_smtpad_ids, pcb_plated_hole_ids, pcb_hole_ids, and pcb_keepout_ids, along with a descriptive message detailing the conflicting component pins or pads. Downstream visualization and export tooling (such as circuit-to-svg) consume this element to display red indicator diamonds and visual link lines between the intersecting land patterns. If left uncorrected, footprint overlaps result in short circuits across incompatible nets, physical part interference, and non-manufacturable PCB Gerber outputs.

Why it happens

The tscircuit core layout evaluator emits pcb_footprint_overlap_error when geometric intersection checks detect that footprint pads, pins, or holes from separate components occupy overlapping 2D coordinates on the board. Common triggers include placing two components at the same explicit pcbX and pcbY coordinates, failing to offset components generated inside iterative loops, choosing an oversized package footprint whose land pattern extends into neighboring parts, or stacking subcircuits without adequate board clearance.

Minimal reproduction

export default () => (
  <board width="20mm" height="20mm">
    <resistor
      name="R1"
      resistance="1k"
      footprint="0402"
      pcbX={0}
      pcbY={0}
    />
    <resistor
      name="R2"
      resistance="1k"
      footprint="0402"
      pcbX={0}
      pcbY={0}
    />
  </board>
)

How to fix it

Separate the conflicting components by adjusting their pcbX and pcbY coordinates or increasing the spacing between adjacent footprint boundaries.

```tsx
export default () => (
  <board width="20mm" height="20mm">
    <resistor
      name="R1"
      resistance="1k"
      footprint="0402"
      pcbX={-2}
      pcbY={0}
    />
    <resistor
      name="R2"
      resistance="1k"
      footprint="0402"
      pcbX={2}
      pcbY={0}
    />
  </board>
)
```

Step 1

• Examine the error message to identify the specific components and pin pads involved in the collision.

Step 2

• Update the pcbX or pcbY props on the conflicting components so that their outer land pattern boundaries do not intersect.

Step 3

• Ensure sufficient clearance between component courtyards and pads according to target fabrication tolerances.

Step 4

• Re-evaluate the circuit layout to verify that all footprint overlap diagnostics are cleared.

Upstream references

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

circuit-to-svg: PCB Error Rendering and Diagnostic Visualization