It appears that when you use the
RecursiveArrayIterator::offsetSet() method to change a value within a JSON object you are iterating over that the new value needs to be of the same type as the original value. I imagine more often than not, at least when dealing with JSON iteration, that the value will be an object or an array because the iterator treats the object like an array. If you try to set it to another data type (i.e. string, integer, etc), PHP will throw a:
Fatal error: Uncaught exception 'InvalidArgumentException' with message 'Passed variable is not an array or object, using empty array instead'
My workaround has been to use
RecursiveArrayIterator::offsetUnset first to nullify the old value and its type and then call
RecursiveArrayIterator::offsetSet() to set the new value.