Action execution fails with KeyError '_cls' when parameters contain '_ref' keys

SUMMARY

Action execution fails with KeyError: '_cls' when action parameters
contain dictionary keys named _ref.

This occurs during execution scheduling (before the action runs) and
results in a 500 Internal Server Error. The issue appears to be caused
by MongoEngine dereference logic misinterpreting dictionaries containing
_ref as document references and attempting to access a missing _cls
field.

Renaming _ref to another key (e.g. object_ref) resolves the issue.

---

STACKSTORM VERSION

st2 3.9.0, on Python 3.8.17

---

OS, environment, install method

• OS: Red Hat Enterprise Linux 8.10 (Ootpa)
• Environment: Virtual machine (VMware)
• Install method: Official StackStorm one-line install script

---

Steps to reproduce the problem

1. Create a simple python-script action:

Action metadata

name: test_ref_issue
runner_type: python-script
entry_point: test.py

parameters:
  data:
    type: object
    required: true

Action code

from st2common.runners.base_action import Action

class TestAction(Action):
    def run(self, data):
        return data

2. Execute the action with a payload containing _ref:

{
  "data": {
    "_ref": "network/test",
    "network": "10.0.0.0/24"
  }
}

---

Expected Results

• Action execution should be successfully scheduled
• Parameters should be passed through unchanged
• Action should run and return the provided input data

---

Actual Results

• Execution fails during scheduling (before the action runs)
• StackStorm returns a 500 Internal Server Error
• The action is never executed

Error message:

KeyError: '_cls'

Relevant stack trace excerpt:

mongoengine/dereference.py
reference_map.setdefault(get_document(item["_cls"]), set()).add(
KeyError: '_cls'

---

Additional Observations

• The issue occurs even with minimal payloads containing _ref
• The issue also occurs when _ref appears in nested dictionaries
• Removing _ref allows execution to succeed
• Renaming _ref to another key (e.g. object_ref) resolves the
  issue
• Other fields such as network, comment, etc. do not cause issues
• This suggests MongoEngine is incorrectly treating _ref-containing
  dicts as document references during execution persistence

---

Workaround

Rename _ref keys before passing data into StackStorm (e.g. _ref →
object_ref), and convert back when needed before calling external APIs
(e.g. Infoblox).

Reproduce the failure with the provided Python action and payload, then trace execution scheduling into persistence and the MongoEngine dereference logic shown in mongoengine/dereference.py. Verify handling of nested dictionaries containing _ref without _cls; done means scheduling succeeds, parameters remain unchanged, and the action returns the input data without a 500 error.