PCB Placement Error (pcb_placement_error)

Diagnostic signature

pcb_placement_error

In the tscircuit toolchain and Circuit JSON data model, pcb_placement_error is emitted when PCB elements—such as component footprints, pads, or vias—are positioned outside the defined board boundary or fail geometric placement constraints.

What it means

The pcb_placement_error diagnostic indicates that one or more physical circuit elements have invalid spatial coordinates on the PCB layer. In the Circuit JSON specification, error elements extending BaseCircuitJsonError capture layout and DRC violations. When type is set to pcb_placement_error, the toolchain has identified that a component (pcb_component), via (pcb_via), test point, or footprint outline exceeds the outer boundary of the board (pcb_board) or violates structural placement rules during layout synthesis.

Why it happens

The tscircuit layout engine and @tscircuit/checks rule validation emit pcb_placement_error when: 1. Explicit component coordinates (pcbX, pcbY) or their bounding boxes place pads and copper features outside the board dimensions specified by the <board> element. 2. PCB vias cross or reside completely outside the board outline polygon. 3. Automatic placement solvers fail to fit all required footprints within the constrained board area without violating boundary limits. 4. Nested subcircuits or groups define board elements that exceed the spatial dimensions allocated to the parent board.

Minimal reproduction

import { Circuit } from "@tscircuit/core"

export const MyCircuit = () => (
  <board width="20mm" height="20mm">
    {/* Component positioned outside the 20mm x 20mm board area */}
    <resistor
      name="R1"
      resistance="10k"
      footprint="0805"
      pcbX="50mm"
      pcbY="50mm"
    />
  </board>
)

How to fix it

Reposition components and vias so their entire footprints remain within the board boundary, or increase the dimensions of the board outline.

```tsx
import { Circuit } from "@tscircuit/core"

export const MyCircuit = () => (
  <board width="20mm" height="20mm">
    {/* Component placed safely within the 20mm x 20mm board centered at (0,0) */}
    <resistor
      name="R1"
      resistance="10k"
      footprint="0805"
      pcbX="0mm"
      pcbY="0mm"
    />
  </board>
)
```

Step 1

• Check the pcbX and pcbY properties of the offending component or subcircuit.

Step 2

• Adjust the coordinates to ensure the component center, pads, and courtyard lie entirely within the half-width and half-height extents of the board.

Step 3

• If the board is too small to contain all components, increase the width and height props on the <board> element.

Step 4

• Re-run the tscircuit build or validation checks (such as checkPcbComponentsOutOfBoard) to confirm all placement errors are cleared.

Upstream references

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

tscircuit/checks: Validity and Design Rule checks for Circuit JSON

tscircuit/circuit-json: Low-level circuit representation specification