tscircuit / circuit-json: pcb_port_not_matched_error

Diagnostic signature

pcb_port_not_matched_error

Defines a trace or routing error emitted when a PCB connection or trace references a port that cannot be matched to a corresponding pad on the target PCB component.

What it means

In the tscircuit toolchain and its Circuit JSON schema, the pcb_port_not_matched_error diagnostic represents a failure to match a logical connection or route endpoint to an existing physical PCB port. Circuit JSON components consist of high-level source definitions, schematic symbols, and physical footprint layouts containing pcb_port, pcb_smtpad, or pcb_plated_hole elements. When a net connection or PCB trace is routed toward a component, the layout engine searches for an associated PCB port matching the pin designation. If the target PCB component lacks a corresponding port definition, this error object is produced.

Why it happens

The diagnostic is emitted during circuit compilation, board layout expansion, or DRC/ERC validation when: 1. A schematic connection or net references a pin name or pin index that does not exist on the selected footprint (such as referencing pin 3 on a two-pin component). 2. A custom footprint defines pads whose port hints or pin numbers do not align with the logical ports declared on the source component. 3. A PCB trace or routing hint explicitly designates a source_port_id or pcb_port_id that cannot be matched with any active pad on the target pcb_component element.

Minimal reproduction

import React from "react";

export const BrokenCircuit = () => (
  <board width="20mm" height="20mm">
    <resistor
      name="R1"
      resistance="10k"
      footprint="0805"
      pcbX={0}
      pcbY={0}
    />
    {/* Pin 3 does not exist on a two-terminal resistor footprint */}
    <trace from=".R1 > .pin3" to=".R1 > .pin1" />
  </board>
);

How to fix it

Ensure all trace and net connections target valid port identifiers that match existing pad numbers on the physical footprint.

```tsx
import React from "react";

export const FixedCircuit = () => (
  <board width="20mm" height="20mm">
    <resistor
      name="R1"
      resistance="10k"
      footprint="0805"
      pcbX={-5}
      pcbY={0}
    />
    <resistor
      name="R2"
      resistance="10k"
      footprint="0805"
      pcbX={5}
      pcbY={0}
    />
    {/* Connect matching physical ports pin2 to pin1 */}
    <trace from=".R1 > .pin2" to=".R2 > .pin1" />
  </board>
);
```

Step 1

• Check the pin names and numbers declared by the footprint assigned to the component.

Step 2

• Update any schematic traces, net connections, or route hints to reference valid existing ports (for example, .pin1 and .pin2 on two-terminal components).

Step 3

• If using a custom footprint, ensure every required pad declares matching port_hints or pin numbers so the compiler can link source ports to pcb_port elements.

Upstream references

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

Circuit JSON Element Definitions: PcbPortNotMatchedError