SourceTraceNotConnectedError

Diagnostic signature

source_trace_not_connected_error

This diagnostic indicates that a trace was declared with selectors that could not be resolved to any valid ports. The tscircuit compiler emits this error during evaluation when trace endpoints fail to match existing components or pins.

What it means

In the tscircuit JSON-based intermediate representation and its associated React renderer, electrical connections between components are defined using trace elements that dynamically select target ports via string queries. A `source_trace_not_connected_error` indicates that the evaluation phase successfully processed the trace declaration, but the internal dependency resolver could not locate matching electrical endpoints for one or more of the provided selectors. Consequently, the toolchain cannot establish a valid netlist connection, meaning that neither the schematic wire nor the physical PCB track can be generated for this path.

Why it happens

This error is emitted by the compiler when the string queries provided to a trace's routing attributes (such as the origin or destination selectors) fail to match any instantiated components or exposed pins in the active layout. This typically occurs due to typographical errors in the selector syntax, referencing a component name that has not been defined, or attempting to connect to a pin that is not exposed by the target component's package footprint. The diagnostic payload will explicitly list the unmatched queries within its `selectors_not_found` property array, identifying exactly which selector segments caused the resolution failure.

Minimal reproduction

export const FaultyTraceBoard = () => (
  <board width="10mm" height="10mm">
    <resistor name="R1" resistance="1k" />
    {/* .U1 and .GND do not exist on this board, triggering the error */}
    <trace from=".R1 > .pin1" to=".U1 > .GND" />
  </board>
);

How to fix it

Update the trace selectors to match valid, instantiated components and their corresponding exposed ports.

```TypeScript
export const FaultyTraceBoard = () => (
  <board width="10mm" height="10mm">
    <resistor name="R1" resistance="1k" />
    <resistor name="R2" resistance="10k" />
    {/* Correctly routes from R1's pin to R2's pin */}
    <trace from=".R1 > .pin1" to=".R2 > .pin2" />
  </board>
);
```

Step 1

• Inspect the diagnostic output to locate the `selectors_not_found` array, which contains the exact query strings that failed to resolve.

Step 2

• Verify the intended target component is declared in the board definition and its name exactly matches the left side of the selector query.

Step 3

• Check the documentation or footprint definition of the target component to ensure it exposes the requested pin name (e.g., verifying whether a pin is named `.pin1`, `.GND`, etc.).

Step 4

• Correct the typography or logic in the `<trace />` path, from, or to attributes so that they align exactly with the instantiated elements.

Upstream references

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

circuit-json Source Trace Not Connected Error Declaration