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

[jlesuer87]

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).