pcb_port_not_connected_error

Diagnostic signature

pcb_port_not_connected_error

A diagnostic indicating that a component port assigned to a net lacks a physical trace connection on the PCB.

What it means

In the circuit-json format used by the tscircuit toolchain, the pcb_port_not_connected_error diagnostic signifies that a printed circuit board port (such as a component pad or terminal) is logically meant to be connected to a net but remains unrouted in the physical layout. The toolchain expects every port defined in a schematic or netlist to have a corresponding pcb_trace linking it to other nodes in the same net. When a port is left floating without any copper trace reaching its coordinate, the validation step emits this error. The resulting array of pcb_port_ids specifies exactly which component terminals are missing their required routing. If ignored, the fabricated board will have an open circuit at these locations.

Why it happens

This diagnostic is emitted when the tscircuit compiler or an integrated design rule check (DRC) scans the generated circuit-json elements and identifies a pcb_port that is part of an active net but does not intersect with any pcb_trace element. This condition typically arises when the built-in autorouter fails to find a valid physical path between components due to spatial constraints, overly dense component placement, or restrictive clearance rules. It also occurs if autorouting is explicitly disabled for the board or a specific trace, and the user omits the manual pcbRoute coordinates required to draw the connection manually.

Minimal reproduction

import { createProject } from "@tscircuit/core"; const project = createProject(); project.add( <board width="10mm" height="10mm" autorouting={false}> <resistor name="R1" resistance="1k" footprint="0402" pcbX={-3} pcbY={0} /> <resistor name="R2" resistance="1k" footprint="0402" pcbX={3} pcbY={0} /> <trace from=".R1 > .pin1" to=".R2 > .pin1" /> </board> ); const circuitJson = project.getCircuitJson(); console.log(circuitJson.filter(el => el.type === "pcb_port_not_connected_error"));

How to fix it

Provide a physical path for the trace either by resolving autorouter blockages or by explicitly providing manual trace coordinates.

```tsx
import { createProject } from "@tscircuit/core"; const project = createProject(); project.add( <board width="10mm" height="10mm" autorouting={true}> <resistor name="R1" resistance="1k" footprint="0402" pcbX={-3} pcbY={0} /> <resistor name="R2" resistance="1k" footprint="0402" pcbX={3} pcbY={0} /> <trace from=".R1 > .pin1" to=".R2 > .pin1" /> </board> ); const circuitJson = project.getCircuitJson(); console.log(circuitJson.filter(el => el.type === "pcb_port_not_connected_error"));
```

Step 1

• Verify that your board dimensions provide enough physical space to route the necessary traces.

Step 2

• Check component placement to ensure pads are not completely obstructed by other parts, keepouts, or conflicting nets.

Step 3

• If you are relying on the autorouter, ensure autorouting is enabled at the board level and the trace level.

Step 4

• If you are manually routing, provide a continuous array of coordinates to the pcbRoute property on the trace component that correctly spans from the source port to the destination port.

Upstream references

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

circuit-json Types Specification: PcbPortNotConnectedError