Open CASCADE Standard_NullValue Exception

Diagnostic signature

Standard_NullValue

Standard_NullValue is an exception raised by Open CASCADE Technology (OCCT) math and geometry foundations when an operation requires a strictly non-zero numerical magnitude or non-null vector norm, but encounters a value equal to zero or within numerical epsilon of zero.

What it means

In Open CASCADE Technology, Standard_NullValue is a specialized runtime exception in the TKernel module that inherits through Standard_RangeError, Standard_DomainError, Standard_Failure, and Standard_Transient. It signifies that a numerical or mathematical method was supplied with or computed a null numerical value (such as a scalar magnitude or vector Euclidean norm of zero) in a context where a non-zero, positive, or unit-normalizable entity is required by definition.

Why it happens

Open CASCADE raises Standard_NullValue (via Standard_NullValue::Raise or the macro Standard_NullValue_Raise_if) in scenarios where mathematical operations cannot proceed with null numerical quantities. The primary cause is calling vector normalization methods (such as math_VectorBase::Normalize or math_VectorBase::Normalized) on a math vector whose Euclidean norm is less than or equal to double::RealEpsilon() (or machine precision). It is also triggered when setting step sizes, intervals, or spatial grid parameters to zero where non-null positive dimensions are mandatory.

Minimal reproduction

#include <iostream>
#include <math_Vector.hxx>
#include <Standard_NullValue.hxx>
#include <Standard_ErrorHandler.hxx>
#include <Standard_Failure.hxx>

int main()
{
    try
    {
        // Create a 3-element math vector with all zero components
        math_Vector nullVec(1, 3, 0.0);

        // math_VectorBase::Normalize() throws Standard_NullValue if norm <= RealEpsilon
        nullVec.Normalize();
    }
    catch (const Standard_NullValue& ex)
    {
        std::cerr << "Caught Standard_NullValue: " << ex.GetMessageString() << std::endl;
        return 1;
    }
    catch (const Standard_Failure& ex)
    {
        std::cerr << "Caught generic Standard_Failure: " << ex.GetMessageString() << std::endl;
        return 2;
    }
    return 0;
}

How to fix it

Check vector Euclidean norms or scalar parameters against RealEpsilon or gp::Resolution before executing operations that require non-zero magnitudes.

```cpp
#include <iostream>
#include <math_Vector.hxx>
#include <Standard_NullValue.hxx>
#include <Standard_Real.hxx>

int main()
{
    // Create a math vector
    math_Vector vec(1, 3, 0.0);

    // Verify norm prior to normalization to avoid Standard_NullValue
    Standard_Real normVal = vec.Norm();
    if (normVal > Epsilon(1.0))
    {
        vec.Normalize();
    }
    else
    {
        // Explicitly handle degenerate zero vector
        std::cout << "Vector has null norm; skipping normalization." << std::endl;
        vec(1) = 1.0; // fallback assignment
        vec.Normalize();
    }

    std::cout << "Normalized vector magnitude: " << vec.Norm() << std::endl;
    return 0;
}
```

Step 1

• Query the vector norm using the .Norm() or .Norm2() member functions before calling .Normalize() or .Normalized().

Step 2

• Compare the magnitude against a numerical tolerance such as Precision::Confusion(), gp::Resolution(), or double::RealEpsilon().

Step 3

• Handle the null-vector edge case explicitly (for example, by assigning a default reference direction, skipping normalization, or signaling invalid input) rather than proceeding unconditionally.

Upstream references

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

math_VectorBase< TheItemType > Class Template Reference

Standard_RangeError.hxx File Reference