Common Pitfalls
A list of mistakes that bite often, with the fix for each.
Forgetting with:
Section titled “Forgetting with:”Connector inputs placed at step level produce a confusing “unknown step parameter” error. Fix: move them inside with:. Anything the connector needs goes in with:; only Zenvara’s own keys (on, timeout, retry, rollback) sit outside it.
Wrapping if: conditions in ${= …}
Section titled “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:
Section titled “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}
Section titled “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
Section titled “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
Section titled “Putting credentials inline”Plain credentials in connection YAML never load — the platform refuses them. This scan does not cover flow or environment YAML: a ${secret:path}-free credential inlined there is neither rejected nor flagged (widening the validator to those two is tracked as ZEN-3917). Fix: always reference ${secret:path}, in every YAML kind, not just connections. See Secrets.
Inventing a generic result key
Section titled “Inventing a generic result key”There is no generic result output. Fix: every connector declares descriptive output field names (body, rows, path, content, …). Use the exact field name from the connector’s <name>.connector.yaml — see the Connector Catalog.
Using a bare type name for a connection
Section titled “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 connector catalog and error messages will usually diagnose a broken flow in one round-trip — see Troubleshooting.