Skip to content
SQLAnvil SQLAnvil SQLAnvil

Troubleshooting

The errors people actually hit, in the order they usually hit them. If your problem isn’t here, see Getting help at the bottom.

Install

Section titled “Install”

npm install -g @sqlanvil/cli fails with EACCES / permission errors — your global npm prefix needs root. Either run without installing (npx @sqlanvil/cli compile .) or change npm’s default directory.

sqlanvil: command not found after install — the npm global bin directory isn’t on your PATH. npm bin -g shows where it is.

Node version errors — SQLAnvil needs Node 20 LTS or later. Check with node --version.

Credentials and connections

Section titled “Credentials and connections”

ENOTFOUND db.<project-ref>.supabase.co — the classic Supabase one. The direct db.<ref> host is IPv6-only; most networks can’t reach it. Use the Session pooler instead: in the Supabase dashboard’s Connect dialog, copy the pooler host verbatim — aws-N-<region>.pooler.supabase.com, port 5432, user postgres.<project-ref> (the ref suffix on the user is required through the pooler).

Authentication failed (Postgres/Supabase) — check the user: through the Session pooler it’s postgres.<project-ref>, not plain postgres. And sslMode should be "require" for any managed database.

.df-credentials.json seems ignored or “invalid” — SQLAnvil uses a flat shape (host/port/database/user/password/sslMode), not Dataform’s nested one. Warehouse examples: Getting Started. Two shape gotchas: BigQuery uses projectId + location (auth via gcloud auth application-default login, or add a "credentials" field with a service-account key); MySQL has no defaultSchema — the defaultDataset in workflow_settings.yaml is the database.

Credentials file committed by accident? init writes it gitignored — if you moved or recreated it, re-add it to .gitignore and rotate the password.

The compile / run / validate loop

Section titled “The compile / run / validate loop”

Three verbs, three different failure classes:

  • sqlanvil compile . needs no database at all. If compile fails, the problem is in your project code: an unresolved ${ref("...")} (no action with that name — check the target schema/name, not just the filename), a config error, or a JS error in includes/.
  • sqlanvil run . needs credentials and real tables. The sample project from init compiles immediately but won’t run until the app_orders declaration points at a table that exists (and the BigQuery source has credentials — or delete that pair).
  • sqlanvil validate . is the “what’s still missing” check — it verifies every action against the warehouse (EXPLAIN-based on Postgres/Supabase, dry-run on BigQuery) without writing anything, and names exactly what’s broken. When in doubt, run validate first.

Authoring gotchas

Section titled “Authoring gotchas”
  • Statements in an action body are separated with --- on its own line — not ;.
  • The settings key is sqlanvilCoreVersion, not dataformCoreVersion (the migrator converts this for you).
  • Warehouse-specific config lives in postgres: {} / mysql: {} / bigquery: {} blocks — don’t hand-roll DDL for indexes or partitions in SQL.
  • Each warehouse guide ends with its own error table — see MySQL in particular.

SQLAnvil Cloud

Section titled “SQLAnvil Cloud”

Opened a PR, no CI check appeared — the SQLAnvil GitHub App isn’t installed on that repository, or the repo isn’t connected to the project. Both steps: Connect a repo.

Branch CI fails immediately on Supabase — branch CI creates an ephemeral Supabase branch, which requires the warehouse project to be on the Pro plan. See Connect Supabase.

Supabase connection stopped working after an update — OAuth scopes are granted per-authorization; if the app’s scopes changed you need to disconnect and reconnect once.

Debugging a failed run — the run page shows each action’s executed SQL and the verbatim warehouse error; Copy failure context bundles it for pasting into a coding agent. If your agent is connected over MCP, get_run_failure fetches the same bundle directly.

Getting help

Section titled “Getting help”

SQLAnvil is deliberately self-service — there’s no ticket queue, and these docs are the support system. When they’re not enough:

Found a fix that belongs on this page? Docs PRs are welcome — every page has an “Edit page” link.