Standard_ImmutableObject

Diagnostic signature

Standard_ImmutableObject

Standard_ImmutableObject is an Open CASCADE Technology (OCCT) domain error exception thrown when an operation attempts to mutate or reassign an object, collection, or buffer that is marked immutable or read-only.

What it means

In Open CASCADE Technology, Standard_ImmutableObject is an exception class belonging to the Standard package in the Foundation Classes module (TKernel toolkit). It inherits from Standard_DomainError, which in turn derives from Standard_Failure and Standard_Transient. The exception signals a violation of immutability guarantees: a mutating member function, key substitution, or in-place write operation was invoked on an instance whose state or interface prohibits modification.

Why it happens

OCCT components and OCCT-based applications emit Standard_ImmutableObject when code attempts to alter an object that has been locked, created as immutable, or designated read-only. This can occur when mutating elements in indexed structures where key updates are prohibited, modifying wrapped read-only memory buffers, attempting to modify shared structures without a copy-on-write detachment, or when application logic explicitly validates object mutability using Standard_ImmutableObject_Raise_if or Standard_ImmutableObject::Raise.

Minimal reproduction

#include <iostream>
#include <Standard_ImmutableObject.hxx>

class ReadOnlyDataWrapper {
public:
  ReadOnlyDataWrapper(bool theIsReadOnly) : myIsReadOnly(theIsReadOnly) {}

  void UpdateValue(int theIndex, double theValue) {
    Standard_ImmutableObject_Raise_if(myIsReadOnly, "ReadOnlyDataWrapper: modification of an immutable object is forbidden");
    (void)theIndex;
    (void)theValue;
  }

private:
  bool myIsReadOnly;
};

int main() {
  ReadOnlyDataWrapper aWrapper(true);
  try {
    aWrapper.UpdateValue(0, 3.14159);
  } catch (const Standard_ImmutableObject& anException) {
    std::cerr << "Standard_ImmutableObject: " << anException.GetMessageString() << std::endl;
    return 1;
  }
  return 0;
}

How to fix it

Ensure the target object is mutable before invoking modifying operations, or create a mutable clone/copy of the immutable object before applying mutations.

```cpp
#include <iostream>
#include <Standard_ImmutableObject.hxx>

class ReadOnlyDataWrapper {
public:
  ReadOnlyDataWrapper(bool theIsReadOnly) : myIsReadOnly(theIsReadOnly) {}

  bool IsReadOnly() const { return myIsReadOnly; }

  void UpdateValue(int theIndex, double theValue) {
    Standard_ImmutableObject_Raise_if(myIsReadOnly, "ReadOnlyDataWrapper: modification of an immutable object is forbidden");
    (void)theIndex;
    (void)theValue;
  }

  ReadOnlyDataWrapper CreateMutableCopy() const {
    return ReadOnlyDataWrapper(false);
  }

private:
  bool myIsReadOnly;
};

int main() {
  ReadOnlyDataWrapper aConstWrapper(true);
  ReadOnlyDataWrapper aMutableWrapper = aConstWrapper.CreateMutableCopy();
  try {
    aMutableWrapper.UpdateValue(0, 3.14159);
    std::cout << "Update succeeded on mutable copy." << std::endl;
  } catch (const Standard_ImmutableObject& anException) {
    std::cerr << "Standard_ImmutableObject: " << anException.GetMessageString() << std::endl;
    return 1;
  }
  return 0;
}
```

Step 1

• Verify whether the object or collection has an immutability or read-only flag set prior to invoking mutation functions.

Step 2

• If modifying existing shared data, create a distinct mutable instance or deep copy of the object rather than modifying the immutable source instance in place.

Step 3

• Perform any mutation or update calls exclusively on the newly created mutable object.

Upstream references

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

Package Standard - Open CASCADE Technology Reference Manual

NCollection_IndexedMap.hxx File Reference - Open CASCADE Technology Reference Manual