Troubleshooting

This page collects common issues users encounter when using Solidean, along with hints on how to resolve them.

Installation & Build

Most installation and build issues stem from missing dynamic libraries, incorrect include paths, or misconfigured build scripts.
Below are the most common cases and their resolutions.

Solidean library (.dll / .so) cannot be found

Cause:
The dynamic library is not in the expected search path.

Resolution:

• Place the solidean.dll (Windows) or libsolidean.so (Linux) in the same directory as your executable
• Alternatively, add the library folder to the system library path (e.g. PATH on Windows, LD_LIBRARY_PATH on Linux)
• For Python, the same rule applies: the .dll/.so must be in a location Python can load

CMake cannot find Solidean

Cause:
The Solidean CMakeLists was not added to your build.

Resolution:

• Use the provided CMakeLists from the SDK, e.g. lang/cpp17/CMakeLists.txt
• Add it to your project via:

  add_subdirectory(path/to/solidean/lang/cpp17)
  target_link_libraries(my_target PRIVATE Solidean::Cpp17)
  

• This links against the dynamic library and makes #include <solidean.hh> available

Python import fails: ModuleNotFoundError: No module named 'solidean'

Cause:
solidean.py is not in a place where Python can resolve imports.

Resolution:

• Ensure solidean.py is on your PYTHONPATH or inside your working directory
• Verify that the .dll/.so is also discoverable by Python (see above)

Linking errors in C or C++ (non-CMake)

Cause:
The dynamic library or headers were not added correctly.

Resolution:

• Include solidean.hh directly
• Link against the Solidean dynamic library (.dll/.so) manually in your build system
• No official demos exist for non-CMake, but setup is minimal: one header + one dynamic library

Namespace or symbol not found

Cause:
Solidean symbols are scoped under the correct namespace but may be referenced incorrectly.

Resolution:

• For C++: use solidean::Context (or the relevant namespace for your API version)
• For Python: use solidean.Context

Technical

My Boolean result is empty or missing parts

Symptoms:

• Union, Difference, or Intersection returns an empty mesh
• Result mesh is unexpectedly missing surfaces

Causes:

• Input meshes were not declared with the correct MeshType
• Supersolid assumptions violated (holes, self-intersections, nested components)
• Winding order inconsistencies

Resolution:

1. Double-check the input MeshType. If the mesh may have intersections or nesting, use Supersolid.
2. Run Operation::Heal on non-supersolid meshes before Boolean operations.
3. For inconsistent winding, flip all input face orientations to ensure consistent solids.
4. Inspect ExecuteResult from Context::Execute, e.g. InputIsNotSolid, InputIsNotSupersolid.

My operation fails with OperandMustBeSupersolid

Cause:
A mesh declared as NonSupersolid was passed to an operation that requires at least Supersolid.

Resolution:
Run the mesh through Operation::Heal to upgrade it to a valid supersolid, then retry the operation.
If a strictly solid mesh is required, combine with Operation::SelfUnion.

My mesh looks correct but ExecuteResult reports an error

Cause:
Solidean continues execution in best-effort mode even when issues are detected (e.g. InputHasSelfIntersections).
The resulting mesh may be usable but flagged as potentially invalid.

Resolution:

• Treat warnings as indicators that your input guarantees were not respected.
• Fix inputs by setting appropriate flags in SurfaceBuilder / MeshBuilder.
• Use Operation::Heal if the input cannot be guaranteed supersolid.

Exported meshes look fragmented or over-triangulated

Cause:

• Using unrolled triangle export (ExportFormat::Triangles) loses connectivity
• ExportOptions not configured to preserve polygon structure

Resolution:

• Prefer ExportFormat::IndexedTriangles or ExportFormat::IndexedPolygons to deduplicate vertices
• Use ExportOption::Manifold to enforce consistent topology
• Use ExportOption::RemoveSpuriousVertices to remove redundant tessellation

I cannot access data from a TypedBlob

Symptoms:

• TypedBlob::GetData returns nothing or fails with Result::DataSlotNotFound

Causes:

• Requested DataSlot not populated due to missing ExportOption
• Operation not executed yet

Resolution:

1. Verify you set the right ExportOption (e.g. VertexPositionF32, PrimitiveID).
2. Ensure you called Context::Execute before accessing blob data.
3. Use TypedBlob::HasData to check which slots are actually present.

Error: OperandFromWrongOperation

Cause:
A MeshOperand created in one operation was used in a different operation.

Resolution:
If you need to reuse a mesh result across operations, first call Operation::Output to materialize it, then Operation::Input in the new operation.

Error: OperationNotYetExecuted

Cause:
Attempting to access the result of an operation (mesh or blob) before Context::Execute was called.

Resolution:
Ensure Context::Execute(op) is invoked and completes before you read results.

Error: IncompatibleArithmetics

Cause:
Meshes defined with different ExactArithmetic kernels were combined in one operation.

Resolution:
All inputs to a single operation must use the same arithmetic kernel.
Re-import or rebuild meshes under a consistent ExactArithmetic.

My queries (area, volume, etc.) return strange values

Cause:

• Query results are accumulated in double precision, not exact arithmetic
• Supersolid interpretation double-counts overlapping regions

Resolution:

• If precise volume/surface semantics are required, ensure you run SelfUnion before queries
• Accept small floating-point accumulation errors as documented
• Contact support if strict error bounds are critical to your application

Performance is unexpectedly slow

Possible reasons:

• Flags like AllowSelfIntersections or AllowSurfaceIntersections introduce heavy checks
• ExecutionMode::Debug enabled, adding validation overhead

Resolution:

• Only enable intersection/nesting flags when strictly needed
• Use Multithreaded execution (default)
• If performance issues persist, please contact support - we are continuously improving performance across a wide range of use cases

Licensing

Licensing issues are handled during Context::Create.
If the context fails to initialize, check the returned Result code for the specific error.

Error: Result::LicenseInvalid

Cause:
The license key is not valid for this installation or has been mistyped.

Resolution:

• Double-check that the correct license key is being used (is currently baked into the shared library)
• Contact support if the license was recently issued but is still rejected

Error: Result::LicenseNoNetwork

Cause:
License verification requires a network connection, but none was available.

Resolution:

• Ensure the machine can reach the licensing server (check firewall / proxy settings)
• Retry when a stable connection is available
• Contact support if offline activation is required

Error: Result::LicenseMustActivateMachine

Cause:
This license requires explicit machine activation.

Resolution:

• Run the activation process provided with your license details (this should be handled automatically)
• Contact support if you need to transfer or reset machine activations

Error: Result::LicenseOutOfMachines / Result::LicenseOutOfCores / Result::LicenseOutOfProcesses

Cause:
The license limits the number of machines, cores, or processes, and those limits have been exceeded.

Resolution:

• Verify you are running within the licensed limits
• Contact support if you need to extend or adjust limits for your use case

Error: Result::LicenseExpired / Result::LicenseOverdue / Result::LicenseSuspended

Cause:
The license is no longer active (expired, overdue, or temporarily suspended).

Resolution:

• Renew or update your license
• Contact support if you believe the license should still be active

Error: Result::LicenseBanned

Cause:
The license was explicitly banned (e.g. due to violation of terms).

Resolution:

• Contact support for clarification and possible remediation