debug-operator

name	debug-operator
description	TRIGGER when operator errors appear or user reports broken behavior. Systematic diagnosis workflow.

Debug Operator Workflow

Systematic approach to diagnosing TD operator errors:

1. Get errors and warnings: get_op_errors with recurse=true on the suspected operator and its children
2. Inspect the operator: get_op to see type, family, parameters, inputs, outputs, children
3. Check connections: get_connections to verify input/output wiring is correct
4. Read DAT content: get_dat_content if the operator is a DAT with script errors
5. Check parameters: get_parameter on specific parameters that might be misconfigured
6. Check performance: get_op_performance if the issue is cook-time related

Common Error Patterns

• Missing input: Operator requires a specific input type — check connections
• Script error in DAT: Read the DAT content and fix the Python/expression
• Parameter out of range: Check parameter values against valid ranges
• Missing operator reference: An expression or parameter references a non-existent operator
• Cook error: The operator can't process its inputs — check input data types match expectations
• Black or empty render: Use capture_top on the intended output TOP, then check display/render flags on the output and upstream ops; missing light or camera (a 3D scene renders black without both); no cooking Null terminating the chain; a bypass flag left on; resolution is 0; alpha is premultiplied/zero so the image is present but invisible; and whether the op is cooking (check cookedThisFrame via get_op_performance, or force a cook). After each fix, use capture_top again to confirm the frame renders correctly.
• Stale content after a file change (cooks clean, shows old pixels): An op can cook with NO errors and the RIGHT resolution yet still hold STALE content. A Movie File In whose par.file changed serves its previous cached texture until it cooks on a real frame advance -- cook(force=True) in the same frame is not enough. And when a TOP chain's output looks exactly ONE frame stale, suspect same-pass reload propagation: a reload applied mid-pass may not reach downstream ops until the next real frame, even under forced cooks in dependency order. Verify CONTENT, not cook state -- read pixels back (numpyArray() / capture_top) at the POINT OF CAPTURE (the chain's output, not the source) and confirm they actually changed across a real frame advance. See rules/td-python.md (Cook Model) and rules/performance.md (Movie Export).