tscircuit: pcb_panelization_placement_error

Diagnostic signature

pcb_panelization_placement_error

Emitted when a PCB board element cannot be placed or packed within the boundary dimensions and spacing constraints of its containing PCB panel.

What it means

The pcb_panelization_placement_error diagnostic is an error element specified in Circuit JSON (PcbPanelizationPlacementError). It indicates that a PCB board (pcb_board) designated as part of a multi-board panel assembly (pcb_panel) has failed geometric placement verification. The diagnostic payload contains identifiers linking the error to the associated pcb_panel_id, pcb_board_id, and optional subcircuit_id, along with a descriptive message detailing the placement conflict.

Why it happens

Upstream circuit processing and layout engines emit this diagnostic under several specific panelization conditions: (1) child boards positioned within a panel exceed the panel outer bounding dimensions (width and height); (2) multiple boards within a panel overlap each other or violate required board-to-board spacing clearances (such as boardGap); (3) automatic packing or grid layout algorithms fail to find a viable non-overlapping arrangement for the specified board set; or (4) explicit manual coordinates on child boards place them outside the permissible panel boundaries.

Minimal reproduction

import { Circuit } from "@tscircuit/core"

const circuit = new Circuit()

// Panel boundary is 50mm x 50mm, but second board is placed at pcbX=25mm with width 30mm, extending to x=40mm (outside panel half-width of 25mm)
circuit.add(
  <panel width="50mm" height="50mm">
    <board width="30mm" height="30mm" pcbX="-15mm" pcbY="0mm" />
    <board width="30mm" height="30mm" pcbX="25mm" pcbY="0mm" />
  </panel>
)

const json = await circuit.toJson()
const errors = json.filter((elem: any) => elem.type === "pcb_panelization_placement_error")
console.log(errors)

How to fix it

Resize the enclosing panel to accommodate all child boards and clearances, adjust individual board coordinates, or modify panel packing and gap parameters.

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

const circuit = new Circuit()

// Increased panel width to 70mm so two 30mm boards fit comfortably with 2mm separation
circuit.add(
  <panel width="70mm" height="50mm">
    <board width="30mm" height="30mm" pcbX="-16mm" pcbY="0mm" />
    <board width="30mm" height="30mm" pcbX="16mm" pcbY="0mm" />
  </panel>
)

const json = await circuit.toJson()
const errors = json.filter((elem: any) => elem.type === "pcb_panelization_placement_error")
console.log(errors) // []
```

Step 1

• Inspect the width and height properties of the <panel /> component relative to the combined dimensions of its child <board /> components.

Step 2

• Ensure sufficient clearance between adjacent boards by adjusting boardGap or verifying explicit pcbX and pcbY coordinates.

Step 3

• If using manual coordinate positioning, ensure every board's extents remain within the panel envelope (from -width/2 to +width/2 and -height/2 to +height/2 relative to the panel center).

Step 4

• If using automatic layout modes (such as grid or pack), reduce individual board sizes or increase the panel dimensions until all boards can be packed successfully.

Upstream references

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

tscircuit/circuit-json README Specification: PcbPanelizationPlacementError Element

tscircuit Props: PanelProps Interface Specification