Unknown Error Finding Part

Diagnostic signature

unknown_error_finding_part

The circuit builder encountered an unhandled exception or unexpected payload (e.g., HTML instead of JSON) while querying an external parts registry.

What it means

The `unknown_error_finding_part` diagnostic is a critical error element injected into the generated Circuit JSON. It indicates that when the `tscircuit` compiler attempted to resolve component properties—such as pinouts or footprints—from an external API, the lookup process crashed or received an invalid response format. Rather than silently omitting the part or returning a standard 'part not found' warning, the toolchain embeds this error to signal a severe data retrieval failure during the compilation phase.

Why it happens

This error is typically caused by network failures, outages in the `tscircuit` registry or `jlcsearch` API endpoints, or a network proxy intercepting the request. The underlying part fetcher strictly expects a structured JSON response from the remote server. If the server instead returns an HTML error page (such as a 502 Bad Gateway or 404 Not Found), or if the TCP connection abruptly drops, the internal parser throws an exception which the builder catches and exposes as an `unknown_error_finding_part` error type.

Minimal reproduction

export default () => (
  <board width="10mm" height="10mm">
    {/* Triggers an external API lookup that fails due to the offline or blocked network state */}
    <chip manufacturerPartNumber="NE555" />
  </board>
)

How to fix it

Restore connectivity to the parts registry API, or bypass the external fetch by explicitly defining the component's footprint and pinout locally.

```tsx
export default () => (
  <board width="10mm" height="10mm">
    <chip
      name="U1"
      footprint="soic8"
      pinLabels={{
        pin1: "GND",
        pin2: "TRIG",
        pin3: "OUT",
        pin4: "RESET",
        pin5: "CTRL",
        pin6: "THR",
        pin7: "DIS",
        pin8: "VCC"
      }}
    />
  </board>
)
```

Step 1

• Verify host internet connectivity and ensure outbound HTTPS requests to the required `tscircuit` API endpoints (such as `jlcsearch.tscircuit.com`) are not blocked by a firewall.

Step 2

• Check the external part registry's availability. If the service is returning 5xx HTTP errors, wait for the service to recover.

Step 3

• To unblock the build immediately, convert the implicit component lookup into an explicitly defined component by supplying the `footprint` and `pinLabels` properties directly in the TSX code.

Upstream references

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

jlcsearch API - tscircuit docs