Simulation Unknown Experiment Error (circuit-json)

Diagnostic signature

simulation_unknown_experiment_error

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.

What it means

When executing hardware simulations using tscircuit (such as via @tscircuit/ngspice-spice-engine), an experiment block directs the underlying solver on what analysis to run (e.g., transient, AC sweep, or DC operating point). If a simulation block requests an experiment type that cannot be mapped to a known SPICE command or is improperly formulated, the evaluation engine cannot safely execute the step. Instead of forcing a catastrophic runtime crash, the tscircuit framework traps the unsupported request and injects a `simulation_unknown_experiment_error` object directly into the output Circuit JSON array to document the failure.

Why it happens

This error occurs because the source `simulation_experiment` defines an invalid, unsupported, or misspelled experiment type (e.g., requesting `magic_sweep` instead of a recognized analysis type). It can also trigger if the requested experiment is valid in a newer version of the `circuit-json` specification, but the installed evaluation engine is outdated and does not yet contain the logic required to parse or translate it to the SPICE backend.

Minimal reproduction

import type { AnyCircuitElement } from "circuit-json";

// Defining an unsupported simulation experiment type.
// When consumed by the tscircuit engine, this results in the engine injecting
// a simulation_unknown_experiment_error object into the resulting JSON array.
const invalidCircuitPayload: AnyCircuitElement[] = [
  {
    type: "simulation_experiment",
    simulation_experiment_id: "sim_1",
    // @ts-expect-error This experiment type is invalid and unsupported
    experiment_type: "unsupported_sweep"
  }
];

How to fix it

Replace the invalid experiment request with a supported analysis type and provide all necessary bounding parameters.

```typescript
import type { AnyCircuitElement } from "circuit-json";

// Provide a recognized simulation experiment type with required parameters
// to ensure the underlying SPICE solver can successfully execute it.
const validCircuitPayload: AnyCircuitElement[] = [
  {
    type: "simulation_experiment",
    simulation_experiment_id: "sim_1",
    experiment_type: "dc_sweep",
    start_voltage: 0,
    end_voltage: 5,
    voltage_step: 0.1
  }
];
```

Step 1

• Locate the `simulation_unknown_experiment_error` within the output Circuit JSON to identify the problematic `simulation_experiment_id`.

Step 2

• Trace the ID back to the source code definition (such as a `<analogsimulation />` tag or raw experiment block).

Step 3

• Update the experiment's analysis type to a recognized SPICE analysis (e.g., `dc_sweep`, `transient`, or `ac_sweep`) supported by your active tscircuit engine.

Step 4

• Ensure all required secondary parameters for the chosen analysis, such as start and stop boundaries or frequency steps, are accurately defined.

Upstream references

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

Circuit JSON Documentation (v0.0.465): SimulationUnknownExperimentError