tscircuit: PCB Component Not On Board Edge Error (pcb_component_not_on_board_edge_error)

Diagnostic signature

pcb_component_not_on_board_edge_error

Emitted by tscircuit when a component constrained or intended to mount at the board perimeter is positioned in the interior of the PCB outline rather than along an outer edge.

What it means

In the tscircuit and circuit-json ecosystem, PcbComponentNotOnBoardEdgeError indicates that a physical PCB component with edge-mounting constraints (such as an edge connector, USB receptacle, or card edge interface) is placed away from the boundaries of the board outline. The circuit-json specification represents this error as an element with type 'pcb_component_not_on_board_edge_error'. The error payload carries diagnostic metadata including 'pcb_component_id', 'pcb_board_id', 'component_center' coordinates, and 'pad_to_nearest_board_edge_distance'. This ensures downstream manufacturing exporters and automated routing passes do not attempt to process edge-dependent interfaces placed in unreachable internal regions of the circuit board.

Why it happens

This error occurs during circuit compilation or DRC placement analysis when the geometric distance between an edge-dependent component's pads/mating interface and the nearest segment of the surrounding pcb_board outline exceeds the allowable tolerance. Typical causes include assigning fixed Cartesian layout coordinates (pcbX, pcbY) that locate the component in the center or interior of the board, changing the board width or height without updating the component's edge offset, or failing to align an edge connector with the board perimeter.

Minimal reproduction

import React from "react"

export default () => (
  <board width="30mm" height="20mm">
    {/* Placing an edge connector at the center of the board */}
    <connector
      name="J1"
      footprint="usb_c"
      pcbX={0}
      pcbY={0}
    />
  </board>
)

How to fix it

Reposition the component so that its pads and mating edge align directly with the outer perimeter of the PCB board outline.

```tsx
import React from "react"

export default () => (
  <board width="30mm" height="20mm">
    {/* Aligned to the left edge of the 30mm wide board (-15mm) */}
    <connector
      name="J1"
      footprint="usb_c"
      pcbX={-15}
      pcbY={0}
      pcbRotation={90}
      allowOffBoard
    />
  </board>
)
```

Step 1

Identify the edge of the board where the connector or edge component should be mounted (top, bottom, left, or right).

Step 2

Update the component's pcbX and pcbY coordinates to place the mating interface on the board boundary (for example, at x = -width/2, +width/2, or y = -height/2, +height/2).

Step 3

Rotate the component using the pcbRotation prop if necessary to ensure the port opening faces outwards from the board boundary.

Step 4

If the connector is designed to intentionally protrude past the board edge, add allowOffBoard={true} to avoid triggering out-of-boundary DRC violations.

Upstream references

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

<connector /> Component Specification

<chip /> Element: Off-Board and Boundary Constraints