Standard_NullObject Exception in Open CASCADE Technology

Diagnostic signature

Standard_NullObject

Standard_NullObject is a runtime exception thrown by Open CASCADE Technology (OCCT) when an operation attempts to access, query, or dereference an uninitialized, null, or empty object reference, such as calling methods on an empty TopoDS_Shape or dereferencing a null opencascade::handle.

What it means

Standard_NullObject is a domain-level exception class in the OCCT Foundation Classes hierarchy, inheriting from Standard_DomainError and Standard_Failure. It indicates that an API precondition requiring a valid, instantiated object or handle was violated because the supplied entity was null. In OCCT, calling topological queries, geometry evaluations, or handle dereferences on a null instance bypasses valid memory or topological data structures and triggers this exception to prevent segmentation faults and undefined behavior.

Why it happens

OCCT raises Standard_NullObject in several core situations: (1) Querying topological properties (such as ShapeType(), Orientation(), or TShape()) on a default-constructed or nullified TopoDS_Shape whose internal TopoDS_TShape pointer is null; (2) Dereferencing an empty opencascade::handle smart pointer via operator-> or operator* when null-checking macros are active; (3) Invoking modeling algorithms or topological builders without setting required input shapes or surfaces; or (4) Accessing child nodes, attributes, or depths on an unallocated or null TDF_Label within the Open CASCADE Application Framework (OCAF).

Minimal reproduction

#include <iostream>
#include <Standard_ErrorHandler.hxx>
#include <Standard_Failure.hxx>
#include <Standard_NullObject.hxx>
#include <TopoDS_Shape.hxx>

int main() {
    try {
        OCC_CATCH_SIGNALS;
        TopoDS_Shape emptyShape;
        // Calling ShapeType() on an uninitialized null shape triggers Standard_NullObject
        TopAbs_ShapeEnum shapeType = emptyShape.ShapeType();
        std::cout << "Shape type: " << shapeType << std::endl;
    } catch (const Standard_NullObject& anException) {
        std::cerr << "Caught expected exception: " << anException.GetMessageString() << std::endl;
        return 1;
    }
    return 0;
}

How to fix it

Check that handles and shape wrappers are populated using .IsNull() before accessing their member methods, and ensure topological builders have generated valid geometry before querying output objects.

```cpp
#include <iostream>
#include <BRepPrimAPI_MakeBox.hxx>
#include <Standard_ErrorHandler.hxx>
#include <Standard_NullObject.hxx>
#include <TopoDS_Shape.hxx>

int main() {
    try {
        OCC_CATCH_SIGNALS;
        // Create a valid solid box shape
        TopoDS_Shape validShape = BRepPrimAPI_MakeBox(10.0, 20.0, 30.0).Shape();
        if (!validShape.IsNull()) {
            TopAbs_ShapeEnum shapeType = validShape.ShapeType();
            std::cout << "Shape type successfully queried: " << shapeType << std::endl;
        }
    } catch (const Standard_NullObject& anException) {
        std::cerr << "Unexpected failure: " << anException.GetMessageString() << std::endl;
        return 1;
    }
    return 0;
}
```

Step 1

• Guard dereference and property inspection calls with an IsNull() check on the handle or shape (e.g., if (!aShape.IsNull()) { ... }).

Step 2

• Ensure transient objects managed by opencascade::handle are properly allocated using standard construction (new T(...)) before invoking member functions.

Step 3

• When using modeling algorithms (such as BRepBuilderAPI or boolean operations), verify algorithm completion with IsDone() before extracting resulting shapes.

Step 4

• When loading geometry from STEP, IGES, or BREP files, confirm that the translation returned valid non-empty shapes before passing them downstream.

Upstream references

Open CASCADE Technology OCCT 7.8.0 — Standard_NullObject.hxx — retrieved 2026-08-11

Open CASCADE Technology User Guide: Foundation Classes

TopoDS_Shape Class Reference - Open CASCADE Technology Reference Manual