Diagnostics

Diagnostics have code, severity, message, and optional ref, file, statement, and hint fields.

Source-intent diagnostics

A missing source-intent diagnostic is useful only when it names the absent source: a schema file, migration file, config field, reviewed hint, or checked workload artifact. Side-effect statements in declarative schema sources still raise extraction diagnostics because they are not schema objects. Side-effect statements in the configured migration corpus are migration source intent and should be modeled or preserved, then validated with check and verify.

Code	Severity	Meaning
`SUPA_PARSE_ERROR`	error	`libpg-query` could not parse the SQL.
`SUPA_PARSE_UNAVAILABLE`	warning	The parser dependency did not expose an expected parser function.
`SUPA_EXTRACT_PARSER_REQUIRED`	error	AST extraction requires the `libpg-query` parser; there is no regex fallback.
`SUPA_EXTRACT_UNSUPPORTED`	error	The source contains DDL that `supaschema` cannot model safely.
`SUPA_EXTRACT_DUPLICATE_OBJECT`	error	Two source statements claim the same object identity.
`SUPA_EXTRACT_SIDE_EFFECT_UNSUPPORTED`	error	The source contains a data/control-plane side-effect statement that is not a replay-safe schema object.
`SUPA_OBJECT_PARSE_FAILED`	error	Object SQL did not parse, so its identity hash fell back to normalized text.
`SUPA_SUPABASE_MANAGED_SCHEMA`	error	A schema listed in `managedSchemas` was edited as declarative source.
`SUPA_SUPABASE_VIEW_SECURITY_INVOKER`	warning	A view in an exposed schema does not set `security_invoker`, so RLS applies as the view owner.
`SUPA_CATALOG_EXTRACT_FAILED`	error	Catalog extraction failed against the supplied database.
`SUPA_CATALOG_SNAPSHOT_VERSION`	warning	A `catalog:` snapshot was produced by a different supaschema model version; regenerate it to keep hashes comparable.
`SUPA_DIFF_LINEAGE_BROKEN`	error	The plan’s from-state does not continue the newest pending supaschema migration in the output directory.
`SUPA_DIFF_LINEAGE_DUPLICATE`	error	A pending supaschema migration already covers this exact from/to transition.
`SUPA_DIFF_EMPTY_PLAN`	error	A disk write was explicitly requested, but the diff planned no operations.
`SUPA_DIFF_OUTPUT_EXISTS`	error	The output migration file already exists; supaschema does not overwrite migrations outside `diff --replace`.
`SUPA_DIFF_CONFIG_DIRTY`	error	A scoped diff cannot prove ownership while `supaschema.config.json` has uncommitted changes. Close the config change with its migration or run an unscoped diff that owns it.
`SUPA_DIFF_GENERATED_CONTRACT_DIRTY`	error	Generated TypeScript/Zod outputs changed before migration generation. Close the existing migration unit before running another diff.
`SUPA_DIFF_MIGRATIONS_DIRTY`	error	The migrations directory has uncommitted files before migration generation. Apply, replace, prune, or close that migration unit first.
`SUPA_DIFF_SCOPED_DIRTY_SCHEMA`	error	A scoped diff found dirty schema files outside the requested schema filter. Close that schema unit before generating the scoped migration.
`SUPA_DIFF_TREE_UNCOMMITTED`	warning	The `dir:` to-source has uncommitted changes, so the generated migration’s lineage end-state fingerprints uncommitted tree state; commit the tree change together with the migration and generated outputs, or the next git-baseline generation blocks with `SUPA_MIGRATION_BASELINE_MISMATCH`.
`SUPA_DIFF_REPLACE_APPLIED`	error	`diff --replace` targeted a migration version already recorded in a configured database history table.
`SUPA_DIFF_REPLACE_APPLIED_STATE_UNVERIFIED`	warning	`diff --replace` could not resolve a database history target, so applied state was not verified.
`SUPA_DIFF_REPLACE_BASELINE_REQUIRED`	error	`diff --replace` could not prove or match the replacement migration’s original lineage baseline.
`SUPA_DIFF_REPLACE_HAND_AUTHORED`	error	`diff --replace` targeted a file without supaschema lineage metadata.
`SUPA_DIFF_REPLACE_NOT_LATEST`	error	`diff --replace` targeted a generated migration older than the configured migration directory tip.
`SUPA_MIGRATION_BASELINE_MISMATCH`	error	The resolved `sources.from` model does not match the generated migration-tree baseline. Recover from the source state that produced the baseline, use `diff --replace`, or — when the pending migration’s end-state was never committed and no target records it as applied — review and delete the pending migration, then regenerate from the current tree.
`SUPA_MIGRATION_BASELINE_FORMAT_DRIFT`	warning	The latest generated migration-tree lineage was produced by a different model format, so old and current fingerprints are not directly comparable. Same-format mismatches still block.
`SUPA_MIGRATION_BASELINE_UNSUPPORTED`	error	The selected before-state does not match the configured migration corpus, or existing migrations cannot prove a generated-lineage baseline for source-backed generation.
`SUPA_MIGRATIONS_STALE_BASELINE`	warning	A pending generated migration’s lineage end-state matches neither the current `git:HEAD` schema fingerprint nor the current tree fingerprint; its baseline is unreproducible. If no target records the version as applied, review and delete it, then regenerate.
`SUPA_MIGRATION_CORPUS_PARSE_SKIPPED`	warning	A configured migration file could not be fully parsed for source intent; destructive changes in that file may still require explicit hints.
`SUPA_PLAN_DESTRUCTIVE_HINT_REQUIRED`	error	A destructive change lacks an explicit hint.
`SUPA_PLAN_ADD_COLUMN_UNSAFE`	error	An additive column change needs explicit migration review.
`SUPA_PLAN_COLUMN_ALTER_HINT_REQUIRED`	error	Column drops and type changes render data-preserving ALTERs only after a destructive-change hint.
`SUPA_PLAN_COLUMN_TYPE_USING_REVIEW`	warning	A column type change rendered an identity `USING` cast; review and replace it for non-trivial conversions.
`SUPA_PLAN_DATA_TRANSITION_REQUIRED`	error	A column drop plus column add looks like a storage transition without reviewed data movement intent in the migration corpus.
`SUPA_PLAN_DEPENDENCY_CYCLE`	error	Dependency ordering produced a cycle.
`SUPA_PLAN_EMPTY_WITH_DRIFT`	error	The plan has no operations but the model fingerprints differ; an empty migration would silently mask real drift.
`SUPA_PLAN_RENAME_HINT_UNMATCHED`	error	A rename hint did not match both source and target objects.
`SUPA_PLAN_RENAME_KIND_MISMATCH`	error	A rename hint maps between different object kinds.
`SUPA_PLAN_RENAME_SET_SCHEMA_UNSUPPORTED`	error	A rename hint attempts to move an object between schemas.
`SUPA_PLAN_RENAME_UNSUPPORTED`	error	The object kind cannot yet be renamed safely by the renderer.
`SUPA_PLAN_RENAME_VERIFY_REQUIRED`	warning	Rename output must be verified against PostgreSQL before release.
`SUPA_PLAN_ROUTINE_RETURN_TYPE_CHANGED`	error	The routine’s return type or OUT parameters changed; `CREATE OR REPLACE` cannot apply it without a hinted drop.
`SUPA_PLAN_VIEW_REPLACE_INCOMPATIBLE`	error	The view drops, renames, reorders, or cannot prove output columns; `CREATE OR REPLACE VIEW` cannot apply it without review.
`SUPA_PLAN_VIEW_REPLACE_VERIFY_REQUIRED`	warning	View output columns are statically unknowable; verify the replacement against PostgreSQL rules.
`SUPA_PLAN_CONCURRENT_INDEX_UNSUPPORTED`	error	`CREATE INDEX CONCURRENTLY` cannot run inside the transaction the migration runner uses.
`SUPA_PLAN_COLUMN_DEPENDENT_REWRITE_REQUIRED`	error	A routine, view, policy, or trigger still depends on a dropped or type-changed column.
`SUPA_PLAN_DEPENDENT_ROUTINE_REORDERED`	warning	A dependent object replacement was ordered before the destructive column alter it must stop referencing.
`SUPA_ROUTINE_BODY_DEPENDENCY_UNKNOWN`	warning	A routine language or body form cannot be statically analyzed for dependencies.
`SUPA_ROUTINE_BODY_PARTIAL_DEPENDENCY`	warning	A PL/pgSQL body was only partially parsed; proven references were kept but dependency confidence is degraded.
`SUPA_ROUTINE_DYNAMIC_SQL_DEPENDENCY_UNKNOWN`	warning	A PL/pgSQL body contains dynamic SQL whose relation and column dependencies cannot be proven statically.
`SUPA_ROUTINE_DEPENDENCY_PROOF_REQUIRED`	error	A relation or type changed while a routine has unproven dependencies. Rewrite the routine, include its rewrite in the same plan, split the migration, or use a reviewed explicit migration.
`SUPA_CHECK_CASCADE`	error	`CASCADE` appears in migration SQL.
`SUPA_CHECK_DROP_IF_EXISTS`	error	A `DROP` statement lacks `IF EXISTS`.
`SUPA_CHECK_CREATE_SCHEMA_GUARD`	error	`CREATE SCHEMA` lacks `IF NOT EXISTS` or a catalog guard.
`SUPA_CHECK_CREATE_EXTENSION_GUARD`	error	`CREATE EXTENSION` lacks `IF NOT EXISTS` or a catalog guard.
`SUPA_CHECK_CREATE_TABLE_GUARD`	error	`CREATE TABLE` lacks `IF NOT EXISTS` or a catalog guard.
`SUPA_CHECK_CREATE_SEQUENCE_GUARD`	error	`CREATE SEQUENCE` lacks `IF NOT EXISTS` or a catalog guard.
`SUPA_CHECK_CREATE_INDEX_GUARD`	error	`CREATE INDEX` lacks `IF NOT EXISTS` or a catalog guard.
`SUPA_CHECK_CREATE_MATERIALIZED_VIEW_GUARD`	error	`CREATE MATERIALIZED VIEW` lacks `IF NOT EXISTS` or a catalog guard.
`SUPA_CHECK_CREATE_VIEW_REPLACE`	error	`CREATE VIEW` lacks `OR REPLACE`.
`SUPA_CHECK_CREATE_ROUTINE_REPLACE`	error	`CREATE FUNCTION` or `CREATE PROCEDURE` lacks `OR REPLACE`.
`SUPA_CHECK_CREATE_TYPE_GUARD`	error	`CREATE TYPE` or `CREATE DOMAIN` is not wrapped in a catalog guard.
`SUPA_CHECK_ADD_CONSTRAINT_GUARD`	error	`ALTER TABLE ... ADD CONSTRAINT` is not wrapped in a catalog guard.
`SUPA_CHECK_CREATE_TRIGGER_REPLACEMENT`	error	`CREATE TRIGGER` is not preceded by `DROP TRIGGER IF EXISTS`.
`SUPA_CHECK_SEARCH_PATH`	error	Migration SQL depends on session `search_path`.
`SUPA_CHECK_SECURITY_DEFINER_SEARCH_PATH`	warning	A `SECURITY DEFINER` routine violates the local empty-`search_path` policy, uses an unqualified relation/type despite implicit `pg_temp` lookup, or has a body whose qualification cannot be proven.
`SUPA_CHECK_FUNCTION_PUBLIC_EXECUTE`	warning	A public-schema function does not explicitly revoke default `PUBLIC` `EXECUTE`.
`SUPA_CHECK_FORWARD_REFERENCE_ORDER`	error	A migration statement references an object or column created later in the same file.
`SUPA_CHECK_ENUM_VALUE_USE_SAME_TRANSACTION`	error/warning	An enum value added in this migration is used later in the same file; transactional runners fail. Error under `transactionMode: "per-migration"`, warning under `per-statement`.
`SUPA_CHECK_NONTRANSACTIONAL_INDEX`	error/warning	`CREATE INDEX CONCURRENTLY` needs transaction wrapping disabled. Error under `transactionMode: "per-migration"`, warning under `per-statement`.
`SUPA_CHECK_NONTRANSACTIONAL_REFRESH`	error/warning	`REFRESH MATERIALIZED VIEW CONCURRENTLY` needs transaction wrapping disabled. Error under `transactionMode: "per-migration"`, warning under `per-statement`.
`SUPA_CHECK_ALTER_COLUMN_TYPE_REWRITE`	warning	`ALTER COLUMN TYPE` can rewrite the table under an `ACCESS EXCLUSIVE` lock.
`SUPA_CHECK_SET_NOT_NULL_SCAN`	warning	`SET NOT NULL` scans the table unless a validated `CHECK` constraint already proves it.
`SUPA_CHECK_DEPARSE_MISMATCH`	warning	A statement does not round-trip through the deparser to an identical parse tree; `normalize: "deparse"` would keep its source text. Known third-party deparser gaps recorded in `src/sql/support.ts` are suppressed.
`SUPA_CHECK_DEPARSE_UNSUPPORTED`	warning	A statement cannot be deparsed for the round-trip proof. Known third-party deparser gaps recorded in `src/sql/support.ts` are suppressed.
`SUPA_NORMALIZE_FIDELITY`	warning	Deparsed SQL did not reparse to the identical parse tree; the object kept its source text under `normalize: "deparse"`. Known object and statement gaps recorded in `src/sql/support.ts` keep source text without warning.
`SUPA_NORMALIZE_UNSUPPORTED`	warning	The deparser cannot render this object; it kept its source text under `normalize: "deparse"`. Known object and statement gaps recorded in `src/sql/support.ts` keep source text without warning.
`SUPA_CORPUS_RECONVERGENCE`	error	The corpus oracle did not converge: residual operations remain after applying the rendered reconciliation to the dirty corpus database, the second apply changed the catalog, or a pipeline stage failed. See Corpus oracle.
`SUPA_CHECK_VOLATILE_DEFAULT_REWRITE`	warning	`ADD COLUMN` with a volatile default rewrites the whole table.
`SUPA_CHECK_INSERT_ON_CONFLICT`	error	`INSERT` statements in migrations must use `ON CONFLICT` for replay safety.
`SUPA_CHECK_DML_REVIEW`	warning	`UPDATE`/`DELETE` statements need explicit idempotency review.
`SUPA_CHECK_POLICY_REPLACEMENT`	error	`CREATE POLICY` should be paired with an explicit prior drop for replacement.
`SUPA_RULE_POLICY_MISSING_PREDICATE`	warning	An RLS policy lacks the `USING` or `WITH CHECK` predicate needed for its command class.
`SUPA_RULE_POLICY_MISSING_REQUIRED_COLUMN`	warning	An RLS policy lacks a column configured in `hints.requiredPolicyColumns` for its table.
`SUPA_RULE_EXPOSED_TABLE_WITHOUT_RLS`	warning	A public table is exposed by API-facing grants without RLS enabled.
`SUPA_RULE_SECDEF_SEARCH_PATH`	warning	A `SECURITY DEFINER` routine violates the local empty-`search_path` policy, contains a shadowable unqualified relation/type reference, or cannot prove its body safe. Empty `search_path` still searches `pg_temp` implicitly for relations and types.
`SUPA_SCAN_CONTRACT_ASSERTION`	warning	A TypeScript assertion appears in a file importing generated database contracts.
`SUPA_SCAN_CONTRACT_IMPORT_RENAME`	warning	A generated contract import was renamed locally.
`SUPA_SCAN_CONTRACT_OVERRIDE_TYPES`	warning	A Supabase query response override bypasses the generated database contract.
`SUPA_SCAN_CONTRACT_RETURNS`	warning	A Supabase query returns override bypasses the generated database contract.
`SUPA_SCAN_CONTRACT_RUNTIME_COPY`	warning	A local constant copies a generated runtime contract root.
`SUPA_SCAN_CONTRACT_USAGE_PARSE`	warning	A TypeScript file in the generated-contract usage scan could not be fully parsed.
`SUPA_SELFCHECK_HASH_MISMATCH`	error	A catalog object hashes differently after its rendered SQL is re-extracted; cross-lane diffs would report a false change.
`SUPA_SELFCHECK_MISSING`	error	A catalog object disappeared when its rendered SQL was re-extracted.
`SUPA_SELFCHECK_UNEXPECTED`	error	Re-extraction produced an object the catalog model does not contain.
`SUPA_VALIDATOR_FAILED`	error	A configured external validator reported diagnostics.
`SUPA_VALIDATOR_UNAVAILABLE`	error	A configured external validator binary was not found.
`SUPA_VALIDATOR_UNKNOWN`	error	The config references an unknown validator.
`SUPA_SYNC_DISABLED`	error	`workflow.migration_sync` disables configured apply/deploy.
`SUPA_SYNC_ENV_UNKNOWN`	error	The selected sync environment is not defined.
`SUPA_SYNC_FINAL_RECONCILE_FAILED`	error	A target still has pending or missing expected versions after the runner completed.
`SUPA_SYNC_MULTI_TARGET_APPLY_UNSUPPORTED`	error	More than one mutation target was selected; cross-target apply is not atomic.
`SUPA_SYNC_REMOTE_APPROVAL_REQUIRED`	error	Automatic remote sync is missing its required runtime approval environment variable.
`SUPA_SYNC_RUNNER_FAILED`	error	The selected migration runner launched or connected, then failed during sync.
`SUPA_SYNC_RUNNER_UNAVAILABLE`	error	The selected migration runner could not be launched or connected.
`SUPA_SOURCE_BASELINE_REQUIRED`	error	Generation could not resolve a source-backed baseline. Pin `sources.from` or review `empty:` for a first migration.
`SUPA_SOURCE_LIVE_DATABASE_FOR_GENERATION`	error	Generation was given a live database source. Use a source-backed baseline, or use inspect/verify/selfcheck/drift/sync safety for database-backed workflows.
`SUPA_SOURCE_MIGRATIONS_DRIFT_UNSUPPORTED`	error	Drift detection cannot use replayed migrations as a source. Use `migrations:` only as a generation before-state.
`SUPA_SOURCE_MIGRATIONS_TARGET_UNSUPPORTED`	error	Generation was given a `migrations:` replay target. Use the matching migration corpus only as `--from`; keep `--to` on a declarative or catalog source.
`SUPA_SYNC_SUPABASE_CLI_CONCURRENT_COMPANION`	error	The Supabase CLI runner cannot safely apply a `.concurrent.sql` companion migration.
`SUPA_SYNC_TARGET_OVERRIDE_MULTI`	error	A database URL or environment override was used while multiple sync targets were selected.
`SUPA_SYNC_TARGET_UNKNOWN`	error	The selected named sync target is not configured.
`SUPA_SYNC_TARGET_URL_UNRESOLVED`	error	The selected sync target’s database URL could not be resolved.
`SUPA_SYNC_VERIFY_URL_UNRESOLVED`	error	Sync could not resolve the disposable database URL required to verify pending migrations before apply.
`SUPA_VERIFY_CLEANUP_FAILED`	warning	A temporary verification database could not be dropped and may need manual removal.
`SUPA_VERIFY_FINGERPRINT_MISMATCH` hints	—	The mismatch hint names the differing objects: missing from the migration result, not present in the target, and definition differs.
`SUPA_VERIFY_FAILED`	error	Temporary database verification failed.
`SUPA_VERIFY_PREEXISTING_DRIFT`	warning	The pending migration converged every object it changed and introduced no new drift, but unrelated drift already present on the target remains for a separate reconciliation.
`SUPA_VERIFY_FINGERPRINT_MISMATCH`	error	Applying the migration twice did not produce the target catalog fingerprint.
`SUPA_VERIFY_ROLE_CAPABILITY`	error	The verification role cannot `CREATE DATABASE`; use a role with `CREATEDB` (on local Supabase stacks prefer `supabase_admin`).
`SUPA_VERIFY_STUB_REFERENCE`	warning	A `verify` failure under `--ensure-environment` references a managed schema that the environment stub only provisions minimally; the failure may be a stub limitation rather than a real migration defect. Confirm by applying the migration to a disposable database that provisions the managed surface.
`SUPA_VERIFY_RECONVERGENCE`	error	The migrated catalog cross-lane diffed against the target model is not empty; the model declares state the catalog cannot reproduce (false drift), or lane parity is broken.

Start

Core workflow

Configure

Tasks

Agents and CI

Evidence

Reference

Source-intent diagnostics

​Source-intent diagnostics

Source-intent diagnostics