CLI error codes

Every code a nextly command can end with, the cause it stands for, and a page on how to fix it.

When a nextly command fails, it ends with the same four lines: what happened, why, what to run next, and a link to the page for its code.

✗ <what happened, in one sentence>
  Why:  <the cause>
  Next: <the command or action that fixes it>
  Docs: <the page for this code>  (<CODE>)

Run the command again with --verbose to add the internal context and the stack below those lines. The exit code is 1.

Each code stands for one cause and keeps that meaning in later releases, so scripts and CI can match on it.

Code	Cause
`ADMIN_EMAIL_INVALID`	`nextly users:create-admin` was given no email, or one that is not an email address.
`ADMIN_EMAIL_IN_USE`	An account already uses the email given for the first administrator.
`ADMIN_NAME_MISSING`	`nextly users:create-admin` was given no name for the administrator.
`ADMIN_PASSWORDS_DIFFER`	The two passwords typed at the prompt differ.
`ADMIN_PASSWORD_MISSING`	No password was given: `NEXTLY_ADMIN_PASSWORD` is not set and none was typed at a prompt.
`ADMIN_PASSWORD_TOO_WEAK`	The administrator's password does not meet the install's password rules.
`BASELINE_LOCK_RELEASED`	The schema lock was released before `nextly migrate:baseline` adopted the database, so nothing was written.
`BLOCK_MANIFEST_STALE`	The committed block manifest does not match what the configuration generates.
`BLOCK_MANIFEST_UNREADABLE`	The block manifest exists but could not be read.
`BLOCK_SCHEMA_DERIVATION_FAILED`	The block document schema could not be derived, because something in the process extended `Object.prototype`.
`BUILDER_MIGRATION_SNAPSHOT_MISSING`	A migration file the Schema Builder wrote has no snapshot beside it, so `nextly migrate` does not apply it.
`BUILDER_RELATION_TARGET_UNKNOWN`	A relationship field in `ui-schema.json` names a collection that neither file declares.
`BUILDER_SLUG_COLLISION`	An entity in `ui-schema.json` has the slug of a collection in `nextly.config.ts`.
`BUILD_GENERATION_FAILED`	The build could not generate its type or Zod schema files.
`BUILD_MIGRATIONS_NOT_APPLIED`	`nextly build --strict` found migrations the database has not applied, or that failed.
`BUILD_STRICT_WARNINGS`	`nextly build --strict` found validation warnings, and `--strict` fails the build on any warning.
`CHECKSUM_MISMATCH`	A migration file no longer matches the checksum `migrate:create` recorded in its snapshot.
`COMPONENT_MAP_OUT_OF_DATE`	`nextly generate:types --check` found the committed component map out of step with the configuration.
`CONFIG_IMPORT_NOT_FOUND`	The configuration file imports a file or package that could not be found.
`CONFIG_INVALID`	The configuration, or a definition it loads, declares something Nextly cannot use.
`CONFIG_INVALID_EXPORT`	The configuration file's default export is not a configuration object.
`CONFIG_LOAD_FAILED`	The configuration file compiled, but threw an error while it ran.
`CONFIG_NOT_FOUND`	The configuration file named with `-c` or `--config` does not exist.
`CONFIG_SYNTAX_ERROR`	The configuration file is not valid TypeScript, so it could not be compiled.
`CONFIG_TOOLING_UNAVAILABLE`	Reading the configuration needs the optional `esbuild` package, which is not installed.
`CORE_DESTRUCTIVE_CHANGE_DECLINED`	A destructive change to Nextly's own tables was not confirmed at the prompt, so none was made.
`CORE_SCHEMA_APPLY_FAILED`	The database refused a change to Nextly's own tables.
`CORE_TABLES_NOT_CREATED`	The command could not create the core tables on a database that has none.
`CORE_TABLES_NOT_RECONCILED`	The database's existing core tables could not be brought up to date before the sync.
`DATABASE_ADAPTER_MISSING`	The database adapter package for the dialect `DATABASE_URL` names is not installed.
`DATABASE_CATALOG_UNREADABLE`	The database catalog could not be read, so the command could not tell which field-group registry table the database uses.
`DATABASE_DIALECT_INVALID`	`DB_DIALECT` names a database Nextly does not support.
`DATABASE_DIALECT_UNKNOWN`	The database type could not be told from `DATABASE_URL`, and `DB_DIALECT` is not set.
`DATABASE_NOT_BASELINED`	The database already has tables but no migration history, and the first migration starts from an empty database.
`DATABASE_UNREACHABLE`	The command could not connect to the database `DATABASE_URL` names.
`DATABASE_URL_MISSING`	`DATABASE_URL` is not set, so the command has no database to use.
`DATABASE_VERSION_UNSUPPORTED`	The database server is older than the oldest version Nextly supports for its dialect.
`DATA_LOSS_CONSENT_MALFORMED`	The data-loss consent names its targets in a form it cannot read, so the command changed nothing.
`DATA_LOSS_CONSENT_NOT_COVERED`	The data-loss consent names what may be deleted, and leaves out something the command would delete.
`DATA_LOSS_CONSENT_REQUIRED`	The command would delete data, no consent covers it, and no terminal is attached to ask.
`DEMOTE_COLLECTION_NOT_FOUND`	`db:sync --demote` names a collection that `nextly.config.ts` does not define.
`DROP_OF_FOREIGN_TABLE`	A migration would drop, rename or change a table, column or index that belongs to a different owner.
`FIELD_GROUP_BACKUP_NOT_CONFIRMED`	`migrate:field-groups --apply` was run without `--backup-confirmed`, so it changed nothing.
`FIELD_GROUP_MIGRATION_IN_FLIGHT`	A field-group storage migration is part-way through on this database, so the command refused to change its schema.
`FIELD_GROUP_STORAGE_REFUSED`	The field-group storage on this database is in a shape the field-group migration will not proceed from.
`I18N_RESTORE_COLLECTION_REQUIRED`	`i18n:restore` was run without `--collection`, so it has no entity to restore.
`I18N_RESTORE_ENTITY_AMBIGUOUS`	`i18n:restore --collection` names more than one kind of entity, and `--kind` does not say which.
`I18N_RESTORE_ENTITY_NOT_FOUND`	`i18n:restore --collection` names no collection, single or field group in the configuration or `ui-schema.json`.
`I18N_RESTORE_KIND_INVALID`	`i18n:restore --kind` is not `collection`, `single` or `field-group`.
`INPUT_REFUSED`	A command refused something it was given or read as not valid, for the reason its message names.
`INTERRUPTED_BEFORE_START`	The command was interrupted while it waited to take a schema lock, before it changed anything.
`INVALID_SNAPSHOT`	A migration's snapshot file is not valid JSON, or not a snapshot this version of Nextly reads.
`LEGACY_BOOKKEEPING_FOUND`	The database still has the migration bookkeeping tables of an earlier Nextly release.
`LOCALIZATION_NOT_PROVISIONED`	`db:sync` could not create the translation tables of a localized entity, so its translations cannot be written or read.
`MEDIA_APPLY_OUTSIDE_PROJECT`	`nextly media orphans --apply` was run from outside the project `--cwd` names, so the database settings it read may be another project's.
`MEDIA_CONFIG_OUTSIDE_PROJECT`	`nextly media orphans --apply` was given a configuration from outside the project, whose storage may be another project's.
`MEDIA_STORAGE_UNLISTABLE`	The media storage cannot list its files, so it cannot be searched for left-behind thumbnails.
`MEDIA_THUMBNAILS_NOT_REMOVED`	Some left-behind thumbnails could not be removed, or could not be checked just before their removal.
`MIGRATION_APPLY_FAILED`	The database refused a statement of a migration or of a schema change.
`MIGRATION_CHECKSUM_MISMATCH`	A plugin's migration changed after it was generated or after it was applied.
`MIGRATION_CREATE_CANCELLED`	A prompt of `nextly migrate:create` was cancelled, so it wrote no migration.
`MIGRATION_DRIFT`	The database matches neither the state a migration starts from nor the state it produces.
`MIGRATION_IRREVERSIBLE`	A migration to roll back has no `-- DOWN` section.
`MIGRATION_MISSING`	A migration recorded as applied has no file in the migrations folder.
`MIGRATION_NAME_REQUIRED`	`nextly migrate:create` was given no name for a migration that is not blank.
`MIGRATION_SQL_UNCHECKABLE`	A migration's SQL is in a form the schema guard cannot read, so it cannot check the migration leaves other owners' tables alone.
`MIGRATION_TAMPERED`	A migration recorded as applied has a file that no longer matches its recorded checksum.
`MISSING_MIGRATION`	A snapshot file in `meta/` has no migration file beside it.
`MISSING_SNAPSHOT`	A migration file has no snapshot file beside it in `meta/`.
`NEXTLY_CORE_DESTRUCTIVE_REFUSED`	Bringing Nextly's own tables up to date needs a destructive change, which `nextly migrate` makes only with `NEXTLY_ALLOW_CORE_DESTRUCTIVE=1`.
`NEXTLY_MIGRATE_LOCK_BUSY`	Another run holds the schema lock, so the command did not start and changed nothing.
`NEXTLY_MIGRATION_CONCURRENT_RUN`	Another run recorded the same migration while this one was running it.
`NEXTLY_MIGRATION_FOREIGN_KEY_VIOLATION`	On SQLite, a migration left rows that reference rows that do not exist, or foreign-key enforcement could not be switched off for it.
`NEXTLY_MIGRATION_PARTIALLY_APPLIED`	A migration that runs outside a transaction failed part-way, now or in its newest attempt, and the statements before the failure stayed applied.
`NEXTLY_MIGRATION_SNAPSHOT_MISSING`	`nextly migrate:resolve --applied` has no snapshot to compare the live schema with.
`NEXTLY_PERMISSION_COLLISION`	A plugin's custom permission repeats another, targets a resource Nextly reserves, or repeats one Nextly creates itself.
`NEXTLY_ROUTE_COLLISION`	Two plugin routes answer the same method and path.
`NEXTLY_ROUTE_INVALID_PATH`	A plugin declares a route whose path does not start with `/`.
`NEXTLY_SCHEMA_CROSS_PLUGIN_RELATION`	A plugin relates to another plugin's entity without declaring that plugin in `dependsOn`.
`NEXTLY_SCHEMA_EXTEND_FIELD_DUPLICATE`	A plugin extends an entity with a field whose name the entity already has.
`NEXTLY_SCHEMA_EXTEND_TARGET_UNKNOWN`	A plugin extends an entity that neither the configuration, a plugin nor the Schema Builder declares.
`NEXTLY_SCHEMA_RELATION_TARGET_MISSING`	A relationship field in the configuration or a plugin names a collection that does not exist.
`NEXTLY_SCHEMA_RENAME_UNKNOWN_TARGET`	A plugin's `.rename()` names an entity the plugin does not contribute.
`NEXTLY_SCHEMA_SLUG_COLLISION`	A plugin contributes an entity whose slug the configuration or another plugin already uses.
`NO_TRANSACTION_NEEDS_BLANK`	`--no-transaction` was given to `nextly migrate:create` without `--blank` or `--plugin`.
`OWNERSHIP_TAKEOVER_REFUSED`	A table or element recorded as one owner's would pass to another, so the change was refused.
`PACKAGE_INSTALL_FAILED`	The package manager could not install the package `nextly add` was given.
`PASSWORD_CLEAR_UNCONFIRMED`	`nextly users:clear-plaintext-passwords --apply` was run without `--confirm-default-hasher`.
`PLUGIN_ADMIN_WIDGET_NOT_JSON`	A plugin's admin widget holds a value that cannot be sent to the browser as JSON.
`PLUGIN_ADMIN_WIDGET_UNDRAWABLE`	A plugin's admin widget describes neither a component nor an archetype the admin can draw.
`PLUGIN_APPLIED_MIGRATION_REMOVED`	A plugin no longer lists a migration the database records as applied.
`PLUGIN_CLIENT_CONFIG_NOT_JSON`	A plugin's `admin.clientConfig` holds a value that cannot be sent to the browser as JSON.
`PLUGIN_COLUMN_NOT_MIGRATED`	A column a plugin contributes to a table is not in the database, because the migration that adds it has not been applied.
`PLUGIN_DEPENDENCY_NOT_INSTALLED`	A plugin to install depends on a plugin that is not installed on this database.
`PLUGIN_DISABLED`	The plugin to install or uninstall is disabled in the configuration, so its hooks would not run.
`PLUGIN_DOCUMENT_VIEW_COLLISION`	Two plugin document views answer the same address.
`PLUGIN_DOCUMENT_VIEW_FIELD_TYPE_UNOWNED`	A plugin scopes a document view to a field type the plugin does not contribute.
`PLUGIN_DOCUMENT_VIEW_INVALID`	A plugin declares a document view with no component, a label that is not text, or a path the admin cannot route.
`PLUGIN_DOWN_KEEPS_TABLES`	A plugin's DOWN migrations, as written, do not drop every table it owns, so a full uninstall would leave some.
`PLUGIN_DOWN_LEFT_TABLES`	A plugin's DOWN migrations ran and left a table it owns in place, so the uninstall was not recorded.
`PLUGIN_ENTRY_EXPORTS_SEVERAL`	The file given to `--plugin` exports more than one plugin, so it is not clear which to generate for.
`PLUGIN_ENTRY_UNNAMED`	The file given to `--plugin` exports no plugin definition with a name.
`PLUGIN_EXTENDS_OUTSIDE_ITS_SCHEMA`	A plugin's `schema.extend` hook extends an entity that is not in the schema its migration module is compiled from.
`PLUGIN_HAS_DEPENDENTS`	Another configured plugin depends on the plugin to uninstall.
`PLUGIN_HOOK_CHANGED_SCHEMA`	On SQLite, a plugin's `onUninstall` changed the database schema before its DOWN migrations ran.
`PLUGIN_HOOK_CHANGED_TABLES`	A plugin's `onUninstall` dropped, renamed or replaced a table its DOWN migrations were to drop.
`PLUGIN_HOOK_HANDLERS_RUNNING`	Event handlers a plugin's install or uninstall hook set off were still running when the command's wait ran out.
`PLUGIN_HOOK_SERVICES_REGISTERED`	A plugin's install or uninstall hook was not run, because the process already had services registered.
`PLUGIN_INSTALL_TARGET_UNCLEAR`	`nextly plugins install` was given both a plugin name and `--all`, or neither.
`PLUGIN_JOB_SLUG_TAKEN`	A plugin declares a job slug that another plugin, a reserved namespace or a built-in job type already uses.
`PLUGIN_LIFECYCLE_LOCK_BUSY`	Another migration held the migrate lock, so a plugin install or uninstall ran nothing.
`PLUGIN_MIGRATIONS_BARREL_UNREADABLE`	The plugin's existing migrations barrel could not be loaded, so `nextly migrate:create` stopped rather than rewrite it.
`PLUGIN_MIGRATIONS_OUT_OF_ORDER`	A plugin lists its migrations in an order other than the order of their names.
`PLUGIN_MIGRATIONS_UNAVAILABLE`	A plugin declares tables or table elements and ships no migrations to create them.
`PLUGIN_MIGRATION_ADDS_UNFILLABLE_COLUMN`	A plugin migration would add a NOT NULL column with no default to a table that already has rows.
`PLUGIN_MIGRATION_BEFORE_APPLIED`	A plugin lists a migration that has not run ahead of one that has.
`PLUGIN_MIGRATION_DROPS_CREATED_SCHEMA`	A generated plugin migration would drop a table or column an earlier migration of the plugin created.
`PLUGIN_MIGRATION_MODULE_EXISTS`	`nextly migrate:create --plugin` would write a migration module where one already exists, so it wrote nothing.
`PLUGIN_MIGRATION_NAME_DUPLICATE`	A plugin ships two migrations with the same name, ignoring case.
`PLUGIN_MIGRATION_NOT_SHIPPED`	A full uninstall needs the DOWN of an applied migration the configured version of the plugin no longer ships.
`PLUGIN_MIGRATION_SQL_MISSING`	A plugin migration changes the schema on this database's dialect and has no statements for it.
`PLUGIN_NEEDS_MIGRATED_DATABASE`	A plugin was installed or uninstalled on a database `nextly migrate` has not run on yet.
`PLUGIN_NOT_FOUND`	The plugin named on the command line is not among the plugins the configuration lists.
`PLUGIN_NOT_INSTALLED`	In production, a configured plugin has not been installed on this database.
`PLUGIN_RESOLUTION_ERROR`	A plugin's declaration could not be resolved: a dependency, a version range, a capability, a name or a setting it declares is missing, in conflict or not valid.
`PLUGIN_ROLLBACK_MODULE_NOT_SHIPPED`	`nextly migrate:down --plugin` names a module the ledger records as applied that the configured version of the plugin no longer ships.
`PLUGIN_ROUTE_MOUNT_INVALID`	A plugin declares a route whose `mount` is neither "plugin" nor "root".
`PLUGIN_ROUTE_ROOT_UNREACHABLE`	A plugin declares a root-mounted route at a path a request never reaches it on.
`PLUGIN_SCHEMA_BEHIND`	In production, a plugin expects a schema version its applied migrations have not reached.
`PLUGIN_SCHEMA_UNINSTALLED`	A plugin that has been uninstalled is still listed in the configuration.
`PLUGIN_SCHEMA_VERSION_MISSING`	The plugin given to `--plugin` declares no `schemaVersion`, which its migrations are numbered by.
`PLUGIN_SCHEMA_VERSION_NOT_ADVANCED`	A plugin's declared `schemaVersion` does not move past the one on its last migration.
`PLUGIN_SETUP_FAILED`	A plugin's `setup` function threw while the configuration was loading.
`PLUGIN_TABLES_NOT_MIGRATED`	A plugin's tables were created by a development push, so no applied migration can undo them.
`PLUGIN_TABLE_IDENTITY_UNREADABLE`	The database could not report the identity of a table a full uninstall drops, so the uninstall could not check its hook left it in place.
`PLUGIN_UNINSTALL_IRREVERSIBLE`	A full uninstall was asked of a plugin with a migration that has no DOWN to undo it.
`PLUGIN_UNINSTALL_KEEP_DATA_MISMATCH`	An unfinished uninstall was run again with the other `--keep-data` setting than the one it began with.
`PLUGIN_UNINSTALL_UNCONFIRMED`	A full plugin uninstall would delete data, and the deletion was not confirmed or consented to, so nothing changed.
`PLUGIN_UNINSTALL_UNFINISHED`	A configured plugin's uninstall began and did not finish, so the app does not start with it.
`PLUGIN_WIDGET_SOURCE_COLLISION`	Two plugins contribute a widget source with the same id.
`PLUGIN_WIDGET_SOURCE_INVALID`	A plugin contributes a widget source with no id, or without the resolver functions a source needs.
`PLUGIN_WIDGET_SOURCE_KIND`	A plugin contributes a widget source of a kind the dashboard does not draw.
`PLUGIN_WIDGET_SOURCE_NAMESPACE`	A plugin contributes a widget source whose id is not in the plugin's own namespace.
`PLUGIN_WIDGET_SOURCE_RESERVED`	A plugin contributes a widget source in a namespace Nextly reserves.
`POSTGRES_SCHEMA_INVALID`	`db.postgres.schema` is not a name PostgreSQL can use for a schema.
`POSTGRES_SCHEMA_MISMATCH`	`db.postgres.schema` and the database adapter's schema option name different PostgreSQL schemas.
`POSTGRES_SCHEMA_UNSUPPORTED`	`db.postgres.schema` names a PostgreSQL schema other than `public`, which Nextly cannot create its tables in yet.
`PRODUCTION_ROLLBACK_UNCONFIRMED`	`nextly migrate:down` was run with `NODE_ENV=production` and without `--yes`.
`PROJECT_ALREADY_INITIALIZED`	The folder already has a `nextly.config.ts`, so `nextly init` did not overwrite it.
`PROMOTE_COLLECTION_NOT_FOUND`	`db:sync --promote` names a collection the Schema Builder has no record of.
`REFUSED_STATEMENT`	A migration holds a statement the runner refuses to run where it is, so nothing in it ran.
`RESOLVE_FILE_NOT_FOUND`	The migration file named to `nextly migrate:resolve` is not in the migrations folder.
`RESOLVE_LOCK_RELEASED`	The schema lock was released before `nextly migrate:resolve` changed the migration's record, so nothing was written.
`RESOLVE_MODE_REQUIRED`	`nextly migrate:resolve` was given none, or more than one, of `--applied`, `--rolled-back` and `--failed-cleanup`.
`RESOLVE_NOTHING_TO_CLEAN_UP`	`nextly migrate:resolve --failed-cleanup` was given a migration with no failed or unfinished attempt.
`RESOLVE_NOT_APPLIED`	`nextly migrate:resolve --rolled-back` was given a migration with no applied run to roll back.
`RESOLVE_PLUGIN_MODULE`	`nextly migrate:resolve --applied` was given a plugin module, which `nextly migrate` records itself.
`RESOLVE_SCHEMA_MISMATCH`	`nextly migrate:resolve --applied` found the live schema does not match the migration's snapshot.
`SCHEMA_DRIFT`	The configuration has schema changes that no migration file holds yet.
`SCHEMA_LOCK_LOST`	Another run took the schema lock while the command still held it, so the two may have changed the schema at once.
`SCHEMA_LOCK_UNAVAILABLE`	The schema lock's row could not be established, so the command refused to run without it.
`SCHEMA_SYNC_IN_PRODUCTION`	`NODE_ENV` is `production`, where schema changes are applied by migrations and never synced automatically.
`SETTINGS_CHANGE_WITHOUT_MIGRATION`	An entity's settings changed in the configuration, and no migration records the change.
`SETUP_ALREADY_COMPLETE`	This install already has an administrator, so setup is complete and the command changed nothing.
`SETUP_IN_PROGRESS`	Another setup holds this install's setup claim, so the command changed nothing.
`SETUP_TOKEN_SET_BY_ENV`	`NEXTLY_SETUP_TOKEN` sets this install's setup token, so there is no generated one to replace.
`UI_SCHEMA_INVALID`	The Schema Builder's `ui-schema.json` holds an entry the manifest's schema rejects.
`UI_SCHEMA_NOT_JSON`	The Schema Builder's `ui-schema.json` is not valid JSON.
`UI_SCHEMA_UNREADABLE`	The Schema Builder's `ui-schema.json` exists but could not be read.
`UNEXPECTED_ERROR`	The command stopped on an error that no other code describes.
`UPGRADE_BACKUP_NOT_CONFIRMED`	`nextly upgrade` would change the database, and no backup was confirmed, with no terminal attached to ask.
`UPGRADE_CANCELLED`	The backup prompt of `nextly upgrade` was answered no, so the upgrade did not run.
`UPGRADE_EVENTS_TABLE_TAKEN`	A table of another shape already has the name `nextly upgrade` moves the migration records into.
`WORKFLOW_CANNOT_ATTACH`	A workflow in the configuration is attached to a collection or Single it cannot run on.

CLI error codes

On this page