PCB Trace Missing Error (pcb_trace_missing_error)

Diagnostic signature

pcb_trace_missing_error

The tscircuit DRC engine emits a pcb_trace_missing_error when a logical trace defined in the schematic lacks a corresponding physical layout path on the board. This usually indicates that the autorouter failed to find a valid path due to congestion or obstacles.

What it means

The `pcb_trace_missing_error` diagnostic indicates that a logical connection defined in the schematic (represented by a `source_trace` element) lacks a corresponding physical layout path (a `pcb_trace` element) in the generated PCB representation. In the tscircuit toolchain, the `circuit-json` standard separates design intention from physical realization. A `source_trace` declares that two or more pins must be electrically connected. If the design evaluation finishes but no physical `pcb_trace` elements successfully connect the assigned `pcb_port` entities, the `@tscircuit/checks` design rule checker flags this condition and emits the missing trace error.

Why it happens

This diagnostic typically occurs when the built-in autorouting engine fails to solve a path between the target components. The autorouter may abort or omit the trace if the path is entirely blocked by keepout zones, if the board layout is too congested with other components and traces, or if the footprint pads are positioned out of bounds. It can also be caused by manual routing mistakes, such as providing an empty path array to a `<trace />` element or inadvertently terminating a manual trace short of the mathematical bounding box of the target pad. Floating-point tolerances on certain pad geometries, such as SMT jumpers, can also occasionally cause the boundary checker to report a trace endpoint as disconnected even when it appears visually aligned.

Minimal reproduction

import { Board } from "@tscircuit/core";

// This layout isolates two components with an impenetrable keepout wall.
// The autorouter cannot find a valid path, resulting in a source_trace 
// that lacks a physical pcb_trace.
export const BlockedTraceReproduction = () => (
  <board width="20mm" height="20mm">
    <resistor name="R1" resistance="1k" footprint="0402" pcbX="-5mm" pcbY="0" />
    <resistor name="R2" resistance="1k" footprint="0402" pcbX="5mm" pcbY="0" />
    
    {/* Keepout wall blocking the top and bottom layers completely */}
    <keepout shape="rect" pcbX="0" pcbY="0" width="2mm" height="20mm" layer="top" />
    <keepout shape="rect" pcbX="0" pcbY="0" width="2mm" height="20mm" layer="bottom" />

    {/* Logical connection requested, but physical route will fail */}
    <trace from=".R1 > .pin1" to=".R2 > .pin1" />
  </board>
);

How to fix it

Relieve routing congestion by moving components, splitting keepouts, or manually defining the trace path to bypass obstacles.

```tsx
import { Board } from "@tscircuit/core";

export const FixedLayout = () => (
  <board width="20mm" height="20mm">
    <resistor name="R1" resistance="1k" footprint="0402" pcbX="-5mm" pcbY="0" />
    <resistor name="R2" resistance="1k" footprint="0402" pcbX="5mm" pcbY="0" />
    
    {/* Keepout wall is split to create a valid routing channel for the trace */}
    <keepout shape="rect" pcbX="0" pcbY="6mm" width="2mm" height="8mm" layer="top" />
    <keepout shape="rect" pcbX="0" pcbY="-6mm" width="2mm" height="8mm" layer="top" />

    {/* Autorouter can now successfully place a pcb_trace through the gap */}
    <trace from=".R1 > .pin1" to=".R2 > .pin1" />
  </board>
);
```

Step 1

• Identify the unrouted net by inspecting the `source_trace_id` or `pcb_component_ids` attached to the error payload.

Step 2

• Increase the board dimensions or reposition components to give the autorouter more spatial clearance.

Step 3

• Ensure that keepout zones or large SMD pads do not completely sever the available routing channels on all layers.

Step 4

• If the autorouter repeatedly fails on a complex path, explicitly define the trace using the `<trace />` element's `path` property to manually route around blockages.

Upstream references

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

circuit-json source: pcb_trace_missing_error.ts