tscircuit DRC: Component Outside Board Error (pcb_component_outside_board_error)

Diagnostic signature

pcb_component_outside_board_error

Emitted by tscircuit when the physical footprint, courtyard, or bounding box of a PCB component extends beyond the perimeter of the parent board outline.

What it means

The pcb_component_outside_board_error diagnostic represents a Design Rule Check (DRC) violation in tscircuit and Circuit JSON. It indicates that a component positioned on the board exceeds the spatial boundaries of the target PCB outline. Within Circuit JSON, the error is represented as an object with the following fields: - type and error_type: Set to "pcb_component_outside_board_error". - pcb_component_outside_board_error_id: Unique identifier for the error element. - pcb_component_id: The identifier of the offending pcb_component. - pcb_board_id: The identifier of the board containing the boundary collision. - component_center: Point coordinates { x, y } of the component center. - component_bounds: Bounding box object { min_x, max_x, min_y, max_y } indicating the outer spatial extents of the component pads and courtyard. - subcircuit_id and source_component_id: Optional references linking back to the source circuit definition. - message: A human-readable description indicating the component name and the extent of the boundary overrun.

Why it happens

During board layout compilation and DRC validation, tscircuit calculates the outer bounds of each component (including copper pads, courtyards, and package geometry) and tests whether the component bounding box falls entirely within the enclosing board outline. This error is emitted when: 1. Explicit placement props (pcbX, pcbY) place the component center outside the board outline or too close to the edge such that the component bounds breach the perimeter. 2. The board dimensions (width, height) are smaller than the span required by the components placed upon it. 3. A custom board outline or cutout polygon excludes the coordinates where a component is positioned. 4. Layout transforms, group offsets, or automatic packing algorithms position a component beyond the board boundary.

Minimal reproduction

export default () => (
  <board width="20mm" height="20mm">
    <resistor
      name="R1"
      resistance="10k"
      footprint="0805"
      pcbX="15mm"
      pcbY="0mm"
    />
  </board>
)

How to fix it

Move the component inside the valid board boundaries or enlarge the board dimensions to encompass the component footprint.

```tsx
export default () => (
  <board width="20mm" height="20mm">
    <resistor
      name="R1"
      resistance="10k"
      footprint="0805"
      pcbX="5mm"
      pcbY="0mm"
    />
  </board>
)
```

Step 1

• Determine the valid coordinate range for the board. For a default centered board with dimensions width and height, valid X coordinates span from -width/2 to +width/2 and Y coordinates span from -height/2 to +height/2.

Step 2

• Adjust the component's pcbX and pcbY props so that the component center and all surrounding pads fall completely within the board perimeter.

Step 3

• If the component position is intended, increase the board's width and height props, or expand the custom outline polygon to encompass the footprint bounds.

Upstream references

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

circuit-json: src/pcb/pcb_component_outside_board_error.ts