Skip to main content

Troubleshoot the Coalesce CLI

Use this page when a coa command or local workflow behaves unexpectedly. Each section names a situation you might hit, then explains what is going on and what to try next.

These patterns come up often while you author pipelines locally or run validation before cloud deploy.

Database or Schema Missing When You Run Create​

You might see messaging that you ran create but the database doesn't exist. coa doesn't create databases or schemas. Create them in your warehouse first, then map them in workspaces.yml.

Ref Columns Show as UNKNOWN Type​

If ref() columns show as UNKNOWN type, check the following:

  1. You're using single quotes inside ref(). Double quotes silently break resolution.
  2. The target Node name and location are spelled correctly.
  3. If you use aggregations through CTEs or JOINs, add explicit casts, for example MAX(col)::TIMESTAMP_TZ.

Validate Shows Column Reference Errors on SQL Nodes​

The Column References scanner produces false positives on SQL Nodes when you use Node Type V2. Aliased columns are flagged as missing source columns. These don't block local create or run but may block coa plan in some environments. Run coa validate --verbose to see which errors are real.

Plan Fails Without Showing Specific Errors​

When coa plan fails with a message like issues preventing deployment and the output doesn't show what is wrong, run coa validate --verbose separately to see specific errors. Common causes include Column References false positives when you author with Node Type V2, or pre-existing reference errors on V1 Nodes. Try a fresh environment. Plan behavior can vary between environments with and without existing deploy state.

V2 Nodes Work in the CLI but Fail in the Coalesce App​

When you author with Node Type V2, the CLI doesn't enforce isRequired config fields from your Node type definition, for example insertStrategy. The Coalesce App enforces them. Add config annotations to your .sql file, for example @insertStrategy('INSERT'). Run coa describe sql-format for the full annotation reference.

UNION ALL Returns Only the First SELECT in a V2 SQL Node​

With Node Type V2, the SQL parser currently captures only the first source block. UNION ALL written as plain SQL is silently dropped. Use the insertStrategy: UNION ALL config approach instead of writing UNION ALL directly in your SQL.

Preview SQL Before You Execute​

Always use --dry-run --verbose, for example coa create --include "{ NODE }" --dry-run --verbose. Check that the table name isn't blank and column types aren't UNKNOWN.

Dry-Run Shows CREATE TABLE With No Columns​

Your SQL likely has a parse error, such as a typo or missing keyword. The SQL parser for Node Type V2 silently produces zero columns when it can't parse the SELECT. Check your SQL syntax carefully.

Validate Reports Error Parsing Repo Files​

Check that data.yml has fileVersion: 3, not fileVersion: 1. Also check for malformed @id or @nodeType annotations in your .sql files.

What's Next?​

Continue with the rest of the CLI documentation when you need setup steps, command syntax, local authoring, deploy workflows, or policy detail.