Common Pitfalls

A list of mistakes that bite often, with the fix for each.

Forgetting with:

Operator inputs placed at step level produce a confusing “unknown step parameter” error. Fix: move them inside with:. Anything the operator needs goes in with:; only Zenvara’s own keys (on, timeout, retry, rollback) sit outside it.

Wrapping if: conditions in ${= …}

Conditions are plain expressions — they’re already in expression context. Fix: if: count > 0 is correct; if: "${= count > 0}" double-evaluates and fails.

Reading from an unnamed for-each:

Unnamed loops are sandboxed — inner state does not escape to the outer payload. Fix: name the loop ($batched:) when you need to collect outputs.

Mixing ${path} and ${= path}

${products} preserves type as an entire value; ${= products} runs it through the expression engine and may stringify it. Fix: use ${path} for whole-value references; reserve ${= …} for actual expressions. See Values & Expressions.

Declaring an output: field that no return: populates

The runtime contract check fails the flow at the very end. Fix: either populate the field or remove it from the output: block.

Putting credentials inline

Plain credentials in flow, connection, or environment YAML never load — the platform refuses them. Fix: always reference ${secret:path}. See Secrets.

Inventing a generic result key

There is no generic result output. Fix: every operator declares descriptive output field names (body, rows, path, content, …). Use the exact field name from the operator’s definition.yaml — see the Operator Catalog.

Using a bare type name for a connection

Bare type names (MsSql instead of zenvara/mssql) load with a deprecation warning for backward compatibility. Fix: always use the qualified zenvara/... form on new connections.

---

When you’re stuck, an MCP-aware assistant that can see your live operator catalog and error messages will usually diagnose a broken flow in one round-trip — see Troubleshooting.