tscircuit DRC / routing diagnostic: pcb_trace_error

Diagnostic signature

pcb_trace_error

In tscircuit and the Circuit JSON data specification, pcb_trace_error denotes a design rule check (DRC) or routing failure associated with a printed circuit board copper trace. It is generated when a trace segment physically intersects incompatible copper geometry on the same layer, violates board boundary limits, or fails endpoint connectivity requirements.

What it means

The pcb_trace_error element is an error diagnostic in Circuit JSON defined by the PcbTraceError interface (inheriting from BaseCircuitJsonError). When emitted by validity checkers (such as @tscircuit/checks) or layout evaluators, it signals that one or more pcb_trace elements contain invalid geometry or routing rule violations. The diagnostic record contains identifiers for the affected pcb_trace_id and source_trace_id, related component and port IDs, an optional center coordinate locating the violation on the PCB canvas, and a descriptive message indicating the nature of the routing fault.

Why it happens

Upstream validation rules (such as checkEachPcbTraceNonOverlapping in @tscircuit/checks or autorouter validation passes) generate pcb_trace_error under several conditions: 1. Same-layer copper collision: Two non-connected trace segments or a trace and an incompatible pad/via intersect or physically overlap on the same copper layer. 2. Endpoint discontinuity: The polyline route of a pcb_trace does not terminate within the geometric boundary or acceptable tolerance of its assigned pcb_port or SMT pad. 3. Board outline violation: A trace segment or via center point extends outside the defined pcb_board outline boundary. 4. Unroutable net path: The layout or autorouting engine failed to synthesize a design-rule-compliant path between designated net terminals.

Minimal reproduction

import { checkEachPcbTraceNonOverlapping } from "@tscircuit/checks"
import type { AnyCircuitElement } from "circuit-json"

const circuitJson: AnyCircuitElement[] = [
  {
    type: "pcb_board",
    pcb_board_id: "board_1",
    center: { x: 0, y: 0 },
    width: 20,
    height: 20,
    thickness: 1.6,
    num_layers: 2
  },
  {
    type: "pcb_trace",
    pcb_trace_id: "pcb_trace_1",
    source_trace_id: "source_trace_1",
    route: [
      { route_type: "wire", x: -5, y: 0, width: 0.5, layer: "top" },
      { route_type: "wire", x: 5, y: 0, width: 0.5, layer: "top" }
    ]
  },
  {
    type: "pcb_trace",
    pcb_trace_id: "pcb_trace_2",
    source_trace_id: "source_trace_2",
    route: [
      { route_type: "wire", x: 0, y: -5, width: 0.5, layer: "top" },
      { route_type: "wire", x: 0, y: 5, width: 0.5, layer: "top" }
    ]
  }
]

const errors = checkEachPcbTraceNonOverlapping(circuitJson)
console.log(JSON.stringify(errors, null, 2))

How to fix it

Resolve copper intersections by rerouting crossing traces onto different layers with vias, altering the trace trajectory, or ensuring endpoints properly land inside target pad boundaries within board boundaries.

```typescript
import { checkEachPcbTraceNonOverlapping } from "@tscircuit/checks"
import type { AnyCircuitElement } from "circuit-json"

const circuitJson: AnyCircuitElement[] = [
  {
    type: "pcb_board",
    pcb_board_id: "board_1",
    center: { x: 0, y: 0 },
    width: 20,
    height: 20,
    thickness: 1.6,
    num_layers: 2
  },
  {
    type: "pcb_trace",
    pcb_trace_id: "pcb_trace_1",
    source_trace_id: "source_trace_1",
    route: [
      { route_type: "wire", x: -5, y: 0, width: 0.5, layer: "top" },
      { route_type: "wire", x: 5, y: 0, width: 0.5, layer: "top" }
    ]
  },
  {
    type: "pcb_trace",
    pcb_trace_id: "pcb_trace_2",
    source_trace_id: "source_trace_2",
    route: [
      { route_type: "wire", x: 0, y: -5, width: 0.5, layer: "bottom" },
      { route_type: "wire", x: 0, y: 5, width: 0.5, layer: "bottom" }
    ]
  }
]

const errors = checkEachPcbTraceNonOverlapping(circuitJson)
console.log(JSON.stringify(errors, null, 2)) // []

```

Step 1

• Identify the conflicting pcb_trace elements using the pcb_trace_id, source_trace_id, and center coordinates in the error object.

Step 2

• If two distinct nets cross, move one segment to another copper layer (e.g., transition from top to bottom layer using a pcb_via).

Step 3

• If the error is caused by trace overlap on the same layer, modify waypoint coordinates or enable autorouter clearance rules so paths do not intersect.

Step 4

• If the error reports a disconnected endpoint, verify that the start and end coordinates terminate squarely inside the intended component pad or via bounding area.

Upstream references

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

tscircuit/circuit-json: Circuit JSON Specification

tscircuit/checks: Validity and Design Rule checks for Circuit JSON