> ## Documentation Index > Fetch the complete documentation index at: https://supaschema.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Diagnostics > SUPA diagnostic codes, severities, meanings, and recovery entry points. 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](/docs/guides/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. |