Canonical explanations and fixes for tscircuit toolchain error signatures.
This error occurs when a PCB component is assigned to an invalid or unsupported board layer. In the tscircuit and Circuit JSON specification, physical components can only be mounted on external surface layers (top or bottom). Placing a component on an internal copper layer or specifying an unrecognized layer string triggers this diagnostic.
Emitted by tscircuit when a component constrained or intended to mount at the board perimeter is positioned in the interior of the PCB outline rather than along an outer edge.
Emitted by tscircuit when two component courtyard boundaries intersect or overlap on the same printed circuit board layer, violating manufacturing placement clearance rules.
In tscircuit and Circuit JSON, pcb_footprint_overlap_error is a PCB design rule violation emitted when physical footprint features—such as surface-mount pads, plated through-holes, non-plated holes, or keepouts—from distinct components collide or overlap on the board canvas.
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.
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.
An error element produced within the tscircuit Circuit JSON tree when one or more source components are configured with invalid, conflicting, or mutually exclusive parameters.
Emitted by tscircuit DRC and placement validation when two PCB pads on the same layer are placed closer together than the allowed minimum clearance rule.
Emitted during design rule checks when an unrelated PCB copper trace is placed closer to a component pad than the permitted minimum clearance distance on the same layer.
Emitted when a PCB board element cannot be placed or packed within the boundary dimensions and spacing constraints of its containing PCB panel.
In the tscircuit toolchain and Circuit JSON data model, pcb_placement_error is emitted when PCB elements—such as component footprints, pads, or vias—are positioned outside the defined board boundary or fail geometric placement constraints.
Defines a trace or routing error emitted when a PCB connection or trace references a port that cannot be matched to a corresponding pad on the target PCB component.
Emitted when tscircuit fails to instantiate or construct a source component or subcircuit element during circuit elaboration, typically due to conflicting, invalid, or malformed component properties.
Emitted by the tscircuit toolchain when a source component or subcircuit element definition is missing a required property necessary for compilation or downstream processing.
Emitted by tscircuit when the physical footprint, courtyard, or bounding box of a PCB component extends beyond the perimeter of the parent board outline.
Emitted by tscircuit when the schematic layout engine fails to compute valid coordinates, bounding geometry, or symbol arrangements for a schematic group or subcircuit.
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.
A design rule check error indicating that two vias on a printed circuit board are placed closer than the required minimum clearance distance.
The tscircuit compiler emits this diagnostic when a schematic component, trace, or net connection attempts to reference a port that does not exist on the specified symbol.
The simulation_unknown_experiment_error diagnostic is emitted when a tscircuit simulation engine encounters an analysis or experiment type it does not recognize, resulting in an error element within the Circuit JSON artifact.
Emitted in the compiled Circuit JSON when a user-provided component property fails validation or does not match the expected format.
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.
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.
A diagnostic indicating that a component port assigned to a net lacks a physical trace connection on the PCB.
Emitted when incompatible I2C pins, such as Serial Data (SDA) and Serial Clock (SCL), are erroneously connected to the same electrical network.
The circuit builder encountered an unhandled exception or unexpected payload (e.g., HTML instead of JSON) while querying an external parts registry.
A Design Rule Check (DRC) error indicating that the distance between a PCB trace and a via is less than the required minimum clearance.