2.8. FAQ / Troubleshooting

Which packages do I need to install to write and submit virtual prototypes?

For writing scripts and submitting them to the SimBricks Cloud you need simbricks-orchestration, simbricks-client and simbricks-cli, plus the Python packages of the components your script imports (e.g. simbricks-qemu-sim-py, simbricks-i40e-sys-py). All of these are pure Python and installable via pip or conda. The simulator binaries are only needed where the simulation actually executes — on the Runners, or on your machine for local execution (see Installing SimBricks Packages (Conda Channel)).

My script fails with AttributeError: module 'simbricks.orchestration.simulation' has no attribute 'QemuSim' (or similar).

Concrete simulator and device classes no longer live in simbricks-orchestration. They come from the component packages under simbricks.components.*, e.g. from simbricks.components.qemu import simulation as qemu_sim for QemuSim. Install the respective simbricks-<x>-...-py package and update your imports (see Component Packages: simbricks.components.*).

Local execution fails because a simulator executable (e.g. simb_net_switch ) is not found.

The orchestration framework resolves simulator executables through $PATH. Install the component’s binary conda package (e.g. simbricks-net-base-sim-bin) from the SimBricks conda channel into the active environment, or run inside the simbricks/simbricks-executor container (see Advanced Setup & Building).

Local execution fails with RuntimeError: Global input directory is not set or cannot find a disk image.

Something in the script names a path that only exists on the Runner — an ExternalDiskImage, a boot_dir=, or a @{SIMBRICKS_PATH:global_input_dir}@ placeholder. Pass --global-input-dir <dir> to simbricks-run so those paths resolve, in the layout described in The global input directory. The images SimBricks publishes need none of this: they are downloaded (The images SimBricks publishes), so check network access to https://disk-images.simbricks.io instead.

QEMU is very slow / warns that KVM is not available.

Fast functional simulation with QEMU uses KVM. Make sure /dev/kvm exists and is accessible (when using Docker, pass --device /dev/kvm). Inside VMs, nested virtualization must be enabled. Without KVM, QEMU falls back to slower binary translation (TCG) — simulations still work, just slower.

gem5 complains about the disk image or kernel.

gem5 only supports raw disk images, and boots the ELF vmlinux. A layered image is built in whichever format the simulator needs, so building one on top of a distro image is the way to run gem5 on it — a downloaded image is qcow2 only (The images SimBricks publishes). The vmlinux is extracted from the image with libguestfs, which needs libguestfs-tools on the Runner and the kernel’s debug package in the image (Boot artifacts). For a prebuilt image of your own, make sure the raw variant is in place (images/<name>/<name>.raw, see The global input directory) and use FileDiskImage so the vmlinux is extracted too, or put it at images/<name>/boot/vmlinux and point an ExternalDiskImage’s boot_dir= at it. Also note that gem5 needs to run with kernel.perf_event_paranoid set to 1 or lower on the host (sudo sysctl -w kernel.perf_event_paranoid=1); in Docker this typically requires --privileged.

My performance measurements are not reproducible / look wrong.

By default SimBricks executes virtual prototypes unsynchronized, which is only meant for functional testing. Enable synchronization in your Simulation Configuration for meaningful end-to-end measurements (see Simulation Configuration).

Where do I find the outputs of a run?

For cloud execution, outputs are stored by the Backend and retrievable via CLI, client library, or the web UI. For local execution, everything is collected under the working directory (default ./out/), with the aggregated simulation output in output/out.json (see Disk Images and Data Flow).

Something else is broken — where do I get help?

Ask on https://join.slack.com/t/simbricks/shared_invite/zt-16y96155y-xspnVcm18EUkbUHDcSVonASlack or open an issue/discussion on GitHub (simbricks/simbricks). Bug reports with the full simulation output and your virtual prototype script are the easiest to help with.