schematic_port_not_found

Diagnostic signature

schematic_error

The tscircuit compiler emits this diagnostic when a schematic component, trace, or net connection attempts to reference a port that does not exist on the specified symbol.

What it means

The `schematic_port_not_found` diagnostic (a subtype of `SchematicError`) is emitted by the tscircuit toolchain when a routing element attempts to attach to a schematic symbol's port that does not exist in the generated `circuit-json` intermediate representation. In the tscircuit architecture, physical and logical components declare specific valid attachment points (ports) for schematic lines. The compiler validates these attachment points during the render phase. When a connection is declared targeting an unknown port identifier on a known component, the compiler flags the missing endpoint to prevent unresolvable schematics.

Why it happens

This error is triggered when developers provide an invalid or misspelled port selector in a trace or net connection string. Common scenarios include referencing a non-existent pin index (such as `.pin3` on a two-pin passive component), using an incorrect naming convention for standard pads (e.g., `.VDD` instead of `.VCC`), or omitting the port declaration entirely when building custom subcircuits. When the toolchain attempts to resolve the endpoint selector against the component's defined schematic ports, the lookup fails, resulting in this diagnostic.

Minimal reproduction

export default () => (
  <board width="10mm" height="10mm">
    <resistor name="R1" resistance="1k" footprint="0402" />
    <trace from=".R1 > .pin3" to="net.GND" />
  </board>
);

How to fix it

Verify the component's available ports and correct the trace selector to match a valid pin.

```TypeScript
export default () => (
  <board width="10mm" height="10mm">
    <resistor name="R1" resistance="1k" footprint="0402" />
    <trace from=".R1 > .pin2" to="net.GND" />
  </board>
);
```

Step 1

• Examine the error output to identify the missing port string and the target component it was attempting to route from or to.

Step 2

• Check the hardware definition of the target component to confirm the correct naming convention for its pins (e.g., ensuring standard passives use `.pin1` and `.pin2`).

Step 3

• Update the `from` or `to` properties in the routing trace element to use the exact valid port selector.

Upstream references

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

circuit-json Specification: SchematicError