A similar problem was reported a while back as SERVER-627. The fix covered $id and $ref cases, but didn't fix it for references containing a $db value. If you check https://github.com/mongodb/mongo/blame/master/db/jsobj.cpp @ line 847 and 847 you'll see that it checks for $ref and $id, but not for $db. This is causing certain upserts to fail with "not okForStorage". Removing the $db value from the references before attempting to upsert avoids the problem, so I'm using that as a workaround for now.

Also, it took me ages to riddle out what was causing this. Is there any way you could give more specific information about the invalid syntax? Something like "okForStorage failed with message: key '$db' is not allowed. Check your record and try again." would have saved an incredible amount of time. "not okForStorage" is just cryptic and unhelpful.