What is the correct way to do an upsert?

You didn’t provide enough information to determine your issue.
Is the collection sharded, if so, what is the shard key.
What is the actual query you are using?

I expect this scenario would fail but have not tried it out.
document 1:
id: 1 (filter)
color: blue (filter)
shape: square (filter)

FindOneAndReplace with upsert:true:
id: 1
color: red
shape: circle

Would fail an “upsert” because the id is the same and would result in a duplicate id.