source_ambiguous_port_reference: Port hint matches multiple non-overlapping pads

Diagnostic signature

source_ambiguous_port_reference

Emitted by tscircuit and circuit-json when a port reference or port hint matches multiple distinct, non-overlapping pads on a component, preventing deterministic netlist and layout resolution.

What it means

The source_ambiguous_port_reference error is emitted during Circuit JSON compilation and evaluation when a port selector, port reference, or port hint resolves to multiple distinct pads or terminals on a component that do not physically overlap to form a single continuous pad. In the Circuit JSON data model, each port connection must uniquely identify a discrete electrical node or pad. When an ambiguous reference is encountered, the toolchain cannot determine which physical pad should receive the connection, generating a SourceAmbiguousPortReference error element in the output.

Why it happens

This error occurs during circuit compilation when the compiler indexes component footprint pins and port hints. If a component defines multiple independent pads with the exact same identifier or hint (such as multiple separate chassis shield pads all labeled 'SH' or 'GND') without grouping them or establishing unique pin indices, referencing that shared identifier in a trace or net creates an unresolvable routing ambiguity. The compilation stage identifies that multiple candidate target pads exist without geometric overlap and emits the diagnostic.

Minimal reproduction

import React from "react"

export const AmbiguousPortCircuit = () => (
  <board width="30mm" height="30mm">
    <chip
      name="U1"
      footprint={
        <footprint>
          <smtpad portHints={["SH"]} pcbX="-2mm" pcbY="-2mm" shape="rect" width="1mm" height="1mm" />
          <smtpad portHints={["SH"]} pcbX="2mm" pcbY="-2mm" shape="rect" width="1mm" height="1mm" />
          <smtpad portHints={["1"]} pcbX="-2mm" pcbY="2mm" shape="rect" width="1mm" height="1mm" />
          <smtpad portHints={["2"]} pcbX="2mm" pcbY="2mm" shape="rect" width="1mm" height="1mm" />
        </footprint>
      }
    />
    <trace from=".U1 .SH" to="net.GND" />
  </board>
)

How to fix it

Assign distinct port hints or pin numbers to non-overlapping footprint pads, or route connections to specific disambiguated port identifiers.

```typescript
import React from "react"

export const DisambiguatedPortCircuit = () => (
  <board width="30mm" height="30mm">
    <chip
      name="U1"
      footprint={
        <footprint>
          <smtpad portHints={["SH1", "shield1"]} pcbX="-2mm" pcbY="-2mm" shape="rect" width="1mm" height="1mm" />
          <smtpad portHints={["SH2", "shield2"]} pcbX="2mm" pcbY="-2mm" shape="rect" width="1mm" height="1mm" />
          <smtpad portHints={["1"]} pcbX="-2mm" pcbY="2mm" shape="rect" width="1mm" height="1mm" />
          <smtpad portHints={["2"]} pcbX="2mm" pcbY="2mm" shape="rect" width="1mm" height="1mm" />
        </footprint>
      }
    />
    <trace from=".U1 .SH1" to="net.GND" />
    <trace from=".U1 .SH2" to="net.GND" />
  </board>
)
```

Step 1

• Locate the component footprint where multiple pads share identical port hint strings.

Step 2

• Update the pad definitions to provide unique pin names or numeric suffixes (for example, change duplicate 'SH' hints to 'SH1' and 'SH2').

Step 3

• Update any schematic or layout traces to reference the distinct port identifiers explicitly.

Upstream references

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

Circuit JSON Specification: Source Components