SourcePinMustBeConnectedError in tscircuit

Diagnostic signature

source_pin_must_be_connected_error

An electrical rules check diagnostic generated by @tscircuit/checks when a component pin marked as requiring a connection is left floating without any assigned source traces.

What it means

The `SourcePinMustBeConnectedError` diagnostic indicates that a component's port is explicitly defined with the `must_be_connected` attribute set to true, but the compiler cannot find any trace or net connected to it. In the `tscircuit` toolchain, electronics logic is represented as a flat array of JSON objects known as Circuit JSON. The upstream evaluation routines scan all `source_port` objects for their connectivity properties. When a port is declared with a connection requirement, the toolchain enforces that a corresponding `source_trace` references this port. If no trace is routed to the port, this validation check fails and emits the error to prevent broken nets in the final printed circuit board or schematic.

Why it happens

This diagnostic is emitted by the `@tscircuit/checks` package during the evaluation of a Circuit JSON array. Specifically, the `checkPinMustBeConnected` validity function filters for `source_port` elements that possess a true `must_be_connected` boolean attribute. It then searches the circuit array for any `source_trace` elements that include the port's identifier within their `connected_source_port_ids` list. If a required port is completely unreferenced by any valid routing elements, it is identified as floating, and the compiler flags the missing connection.

Minimal reproduction

[
  {
    "type": "source_component",
    "source_component_id": "comp_1",
    "name": "IC1"
  },
  {
    "type": "source_port",
    "source_port_id": "port_1",
    "source_component_id": "comp_1",
    "name": "VCC",
    "pin_number": 1,
    "must_be_connected": true
  }
]

How to fix it

Connect the floating port to a valid trace, or remove the connection constraint if the floating state is intentional.

```json
[
  {
    "type": "source_component",
    "source_component_id": "comp_1",
    "name": "IC1"
  },
  {
    "type": "source_port",
    "source_port_id": "port_1",
    "source_component_id": "comp_1",
    "name": "VCC",
    "pin_number": 1,
    "must_be_connected": true
  },
  {
    "type": "source_port",
    "source_port_id": "port_2",
    "source_component_id": "comp_2",
    "name": "VCC_SRC",
    "pin_number": 1
  },
  {
    "type": "source_trace",
    "source_trace_id": "trace_1",
    "connected_source_net_ids": [],
    "connected_source_port_ids": [
      "port_1",
      "port_2"
    ]
  }
]
```

Step 1

• Examine the component definition to locate the port identified by the diagnostic's `source_port_id`.

Step 2

• If the pin is critical for operation (e.g., power, ground, or a required signal line), define a net or trace that connects to this port.

Step 3

• Ensure that the connecting `source_trace` element explicitly references the port identifier in its `connected_source_port_ids` string array.

Step 4

• If the pin is safely left unconnected in your specific circuit context, update the component's port attributes to remove the `must_be_connected` flag or set it to `false`.

Upstream references

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

@tscircuit/checks API Declarations