tscircuit / circuit-json: pcb_component_invalid_layer_error

Diagnostic signature

pcb_component_invalid_layer_error

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.

What it means

In the Circuit JSON data model, physical parts on a printed circuit board are represented as pcb_component elements linked to their respective schematic and source definitions. The pcb_component_invalid_layer_error diagnostic indicates that a component definition has been placed on a layer where physical components cannot reside. Physical surface-mount and through-hole electronic components must be mounted on outer board surfaces: either the top layer or the bottom layer. When a component's layer property is set to an inner copper layer (such as inner1, inner2, or custom plane layers) or an invalid LayerRef string, the validator records a PcbComponentInvalidLayerError object in the Circuit JSON output.

Why it happens

The diagnostic is emitted during PCB compilation or Circuit JSON validation under the following conditions: 1. A component element (such as resistor, capacitor, chip, or custom footprint) explicitly defines layer or pcbLayer set to an internal layer (for example, layer='inner1'). 2. A component receives an invalid or malformed LayerRef identifier not recognized as 'top' or 'bottom'. 3. Automated layout, transformation scripts, or board conversions incorrectly propagate internal trace routing layers onto component surface placement definitions.

Minimal reproduction

import { Circuit } from "@tscircuit/core"

export const InvalidComponentLayer = () => (
  <board width="20mm" height="20mm">
    <resistor
      name="R1"
      resistance="10k"
      footprint="0805"
      pcbX={0}
      pcbY={0}
      layer="inner1"
    />
  </board>
)

const circuit = new Circuit()
circuit.add(<InvalidComponentLayer />)
await circuit.render()

const errors = circuit.getCircuitJson().filter(
  (element) => element.type === "pcb_component_invalid_layer_error"
)
console.log(errors)

How to fix it

Update the component placement layer to either 'top' or 'bottom'.

```typescript
import { Circuit } from "@tscircuit/core"

export const ValidComponentLayer = () => (
  <board width="20mm" height="20mm">
    <resistor
      name="R1"
      resistance="10k"
      footprint="0805"
      pcbX={0}
      pcbY={0}
      layer="top"
    />
  </board>
)

const circuit = new Circuit()
circuit.add(<ValidComponentLayer />)
await circuit.render()

const errors = circuit.getCircuitJson().filter(
  (element) => element.type === "pcb_component_invalid_layer_error"
)
console.log(errors)
```

Step 1

• Identify the affected component using the source_component_id or pcb_component_id reported in the diagnostic.

Step 2

• Check the layer or pcbLayer prop assigned to the component in the TSX markup or Circuit JSON definition.

Step 3

• Change the layer property from the internal or invalid layer name (such as 'inner1') to a valid external layer reference: 'top' or 'bottom'.

Step 4

• Re-render the circuit and verify that no pcb_component_invalid_layer_error items remain in the output Circuit JSON.

Upstream references

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

pcb_component_invalid_layer_error.ts - tscircuit/circuit-json