Troubleshooting is split across two pages: this page covers build/setup problems and gives a general diagnostic checklist, while the runtime error catalogue — specific error messages and their resolutions — lives in Runtime errors and diagnostics.

Build and setup issues

Conan/CMake configuration fails

Verify toolchain prerequisites in Setup developer environment.
Re-run profile detection (conan profile detect --force) if compiler config changed.
Reinstall dependencies with --build=missing.

Missing package or remote access errors

Verify you are using the correct Conan remotes and credentials.
Confirm access rights to private package repositories (if applicable).

Runtime issues

Simobject library file not found in one of: ...

Typical causes:

LibName in XML does not match available runtime library name.
Build type mismatch (Debug/Release) between executable and SimObject library.
Visualization mismatch (library built with/without visualization versus executable).

Actions:

Run from the playpen/bin directory: a LibName without a path separator is looked up in the SimObjectLibraries sub-directory of the working directory.
Verify referenced libraries are present and named correctly. The message quotes both paths tried — the plain name and the fhsim_-prefixed fallback.
Rebuild all related components with matching options.

Note: If the file is found but cannot be loaded, the message is instead In FhSimDll: Could not load library "..." from directory "..." (or In FhVisDll: from the visualization loader), which points at a missing runtime dependency rather than a missing file.

Simulation exits before visualization starts

Check logoutput.txt (or configured log file).
Verify XML syntax and required sections (OBJECTS, INTERCONNECTIONS, INITIALIZATION, SIMULATION).
Validate integrator/provider setup against SIMULATION section.

Visualization startup issues

Check Ogre.log for renderer/resource errors.
Ensure GPU/driver stack is updated.
If needed, remove stale ogre.cfg to regenerate renderer settings.

License errors

Set SFH_LICENSE_FILE to a valid license file path, or place license.lic in the working directory.
Confirm the license matches your product/build entitlement.

FMU export and co-simulation problems

Exporting a model with FhFmuExport and running the result in a co-simulation master have their own catalogue of symptoms — a render window opening in CI, two FhSim FMUs that will not coexist in one process, a parameter write refused mid-run, an export that stops with a non-zero exit code. They are collected in FMU export and co-simulation, and the tool itself is documented in FMU tools.

Simulation is slow, unstable, or produces NaN/Inf

FhSim has a built-in diagnostics subsystem that reveals why a run misbehaves (collapsing step size, a specific state forcing small steps, a wrong analytical Jacobian, or where a NaN/Inf first appears). Enable it via the <Diagnostics> element and, if useful, view the results in the browser. See the worked recipes in Diagnostics cookbook. For making a correct run faster, see Performance tuning.

Diagnostic checklist

Run <Executable> --help to verify executable availability.
Run with a known-good example input file.
Increase console/file verbosity to capture detailed diagnostics.
Reduce scenario complexity to isolate failing object/connection.