Plugin Error Reference
The fail-fast boot errors a plugin can trigger — what each means and how to fix it.
Alpha (
0.x) — pin your versions. The plugin API surface is now stable; the packages are still alpha.
Nextly validates plugins fail-fast at boot: a bad plugin config stops startup with a specific error rather than failing later in unclear ways. Each error is a NextlyError with a stable code; the specific cause is in logContext.reason. (The user-facing message is generic — assert on code / logContext.reason in tests.)
Resolution
| Code | Status | Cause | Fix |
|---|---|---|---|
PLUGIN_RESOLUTION_ERROR | 500 | A dependsOn is missing, a dependency cycle exists, or a nextly/dependency version range is incompatible with what's installed. logContext.reason ∈ missing-dependency, dependency-cycle, invalid-nextly-range, core-incompatible, version-incompatible, optional-version-incompatible, capability-not-listed (a plugin declares capabilities.db.rawSql but the app does not list it in db.rawSqlPlugins, or a plugin declares capabilities.auth.login or contributes a determineUser hook — which decides who is signed in — without the app listing it in auth.loginPlugins), capability-added-by-setup (a setup transformer gave a plugin a capability the app lists — rawSql, or the login capability, which a capabilities.auth.login declaration and a determineUser hook are both spellings of: it added the plugin, renamed a plugin onto a name no configured plugin declaring it held, or set the flag or added the hook on a plugin whose manifest does not declare it), plugin-code-replaced-by-setup (a setup transformer replaced the lifecycle functions or contributes of a plugin that declares rawSql or is login-capable; logContext.path names what changed), limit-rule-invalid (a contributes.limits rule outside its documented bounds; logContext.plugin and logContext.rule name it, and logContext.problem says what it must be), plugin-name-reserved (a plugin named app, in any letter case, the owner the site's own permissions are stored under). Also raised for a route option that cannot mean what it says, with logContext.reason invalid-route-options and the problem in logContext.problem: a method other than GET, POST, PATCH, PUT or DELETE (in capitals), rawBody on a method with no body, a rateLimit that is not "auth", "general" or { max, windowMs }, or csrf: false with public: true. | Install/declare the missing dependency, break the cycle, or widen/correct the version range. For invalid-route-options, correct the route's options as the problem says. For capability-not-listed, review the plugin, then add the line the message names, such as db: { rawSqlPlugins: ["@acme/nextly-reports"] } or auth: { loginPlugins: ["@acme/google-auth"] }, to nextly.config.ts; under createTestNextly the message names its pluginConsent option instead. For capability-added-by-setup, declare the capability in the manifest of the plugin the app configures — capabilities.db.rawSql for the raw-SQL grant, capabilities.auth.login or a determineUser hook for the login grant. For plugin-code-replaced-by-setup, leave the definitions of plugins that declare rawSql or the login capability as configured in your transformers. For limit-rule-invalid, bring the rule within the bounds the message names. For plugin-name-reserved, give the plugin another name. |
Schema
| Code | Status | Cause | Fix |
|---|---|---|---|
NEXTLY_SCHEMA_SLUG_COLLISION | 409 | Two sources (a plugin and code/another plugin) contribute the same collection/single/component slug. | Rename one entity, or have the integrator .rename() the plugin's slug. |
NEXTLY_SCHEMA_RELATION_TARGET_MISSING | 400 | A relationTo points at a slug that isn't in the merged schema. | Point the relationship at an existing slug (core users/media are always valid). |
NEXTLY_SCHEMA_RELATION_UNRESOLVED | 400 | A relation a plugin's or the app's table declares (relations, or the edge a col.ref() carries) names a table, or a column at either end, that no table has once every table is registered: a misspelled targetTable, say. logMessage names each relation, and logContext.relations lists them as <table>.<relation>. Raised at boot, before plugins initialise; in development it is reported once the boot's schema apply has registered what migrations created, without stopping the dev server. | Point the relation at a table that exists, or correct the column it names. A relation to a collection or Single joins its id and names no toColumn. |
NEXTLY_SCHEMA_EXTEND_TARGET_UNKNOWN | 400 | contributes.extend targets a slug that doesn't exist in the merged schema (e.g. a Builder-only entity during the code-first gap). | Target an existing code/plugin entity, or declare a dependsOn on the plugin that owns it. |
NEXTLY_SCHEMA_EXTEND_FIELD_DUPLICATE | 409 | contributes.extend adds a field name already present on the target. | Use a different field name (configurable field names resolve collisions). |
NEXTLY_SCHEMA_CROSS_PLUGIN_RELATION | 409 | A plugin relates to (or extends with a relation into) another plugin's entity without declaring dependsOn on it. | Add the other plugin to dependsOn. |
NEXTLY_SCHEMA_RENAME_UNKNOWN_TARGET | 400 | .rename({ from: to }) names a from slug the plugin doesn't contribute. | Rename only slugs the plugin actually declares. |
Transforms
A refused contributes.transforms change is a VALIDATION_ERROR. Each entry in its
errors names the transform in path (plugin:<name>.transform[<index>]) and the rule
in code:
errors[].code | Cause | Fix |
|---|---|---|
TRANSFORM_DEPENDENCY_MISSING | A plugin transforms an entity another plugin declares without listing that plugin in dependsOn. | Add the owning plugin to dependsOn. |
TRANSFORM_TABLE_CHANGED | A transform changes the dbName, status or localized setting of another plugin's entity, or of any entity another plugin has added a field to, or removes or changes one of a plugin entity's unique compound indexes. | Leave the entity's tables as its owner set them. |
TRANSFORM_FIELD_PROTECTED | A transform removes, or changes the storage of, a field another plugin declared: its type, column, size, required, unique, hasMany or repeatable, relation target or translation, or the type of a JSON-stored or password field. | Leave the field's storage alone; only the plugin that declared it may change it. |
TRANSFORM_BEHAVIOUR_PROTECTED | A transform removes, replaces, moves or repeats an access rule, hook, admin setting or function (a validator, a function default, a nested one such as preview.url) a third plugin contributed. | Add that plugin to dependsOn, or leave what it contributed in place. |
A transform whose result its entity's own definition would refuse, such as a collection's
db: { idType: "serial" }, carries that definition's code (DB_ID_TYPE_INVALID here),
and its message names the plugin.
Schema lifecycle
| Code | Status | Cause | Fix |
|---|---|---|---|
PLUGIN_DEPENDENCY_NOT_INSTALLED | 409 | nextly plugins install was run for a plugin whose dependency has unapplied migration modules, was never installed by the install command, was uninstalled, has an uninstall that did not finish, or is not configured. Nothing is changed. | Install each dependency the message lists, in the order it lists them, then install the plugin again. |
PLUGIN_HAS_DEPENDENTS | 409 | nextly plugins uninstall was run for a plugin that another enabled plugin depends on. | Uninstall or disable the dependents first. |
PLUGIN_UNINSTALL_WOULD_DROP_OTHERS | 409 | A full nextly plugins uninstall would drop a column, index, key or check another owner built on the plugin's schema, or break a key or relationship field pointing into it. | Remove each one the message names in its owner's code and migrate, or uninstall with --keep-data. |
PLUGIN_UNINSTALL_IRREVERSIBLE | 409 | A full uninstall needs a migration module that has no DOWN statements for this database's dialect, the plugin's tables were created by a development push and no applied module can undo them (logContext.reason is no-applied-module), an applied module is one the configured version no longer ships (module-not-shipped), or the DOWNs leave one of the plugin's tables in place (down-leaves-tables). Nothing is changed. | Uninstall with --keep-data, or ship a DOWN for that module. For a development push, drop the tables with a migration or reset the development database. |
PLUGIN_UNINSTALL_UNCONFIRMED | 409 | nextly plugins uninstall would drop tables, or run a DOWN that drops a column, and nobody consented: no terminal to ask, and no --accept-data-loss covering each one (--yes does not consent to deleting data). What it would drop is listed before the error. Nothing is changed. | Re-run with --accept-data-loss to drop them, or with --keep-data to keep them. |
PLUGIN_SCHEMA_BEHIND | 409 | At boot, a plugin declares a newer schemaVersion than its applied migrations reach. | Run nextly migrate, or nextly plugins install <name>. After a consent refusal at start, give the consent the error names. |
PLUGIN_NOT_INSTALLED | 409 | At a production boot, an enabled plugin that nextly plugins install has not installed on this database, whether or not migrations run at boot. A disabled plugin is not required to be installed. Development only warns. | Run nextly plugins install <name> for each plugin the message names. |
PLUGIN_SCHEMA_UNINSTALLED | 409 | At boot, a plugin that was uninstalled, with or without --keep-data, is still listed in the config. Refused in every environment. | Run nextly plugins install <name> to reinstate it, or remove it from the config. |
PLUGIN_UNINSTALL_UNFINISHED | 409 | At boot, a plugin whose uninstall began and did not finish is still listed in the config, refused in every environment; or nextly plugins uninstall was run again the other way, with or without --keep-data, from how it began. Nothing is changed. | Run the uninstall again the way it began (the message names it) to finish it, or nextly plugins install <name> to reinstate the plugin. |
PLUGIN_COMMAND_FROM_OLDER_RELEASE | 409 | nextly plugins install or nextly plugins uninstall ran in production from a Nextly release older than the one the database records as having set the preset roles' grants. Nothing is changed. | Run the command from the release the message names, or a newer one. See the CLI error page. |
PLUGIN_MIGRATIONS_UNAVAILABLE | 409 | nextly migrate found tables, or columns and indexes added to another plugin's table, from a plugin that ships no migration modules, so production has no way to create them. | Generate the plugin's modules with nextly migrate:create --plugin <name>. |
PLUGIN_SCHEMA_VERSION_NOT_ADVANCED | 409 | nextly migrate:create --plugin found schema changes, and the plugin's schemaVersion is not past its last module's. | Raise schemaVersion, then generate again. |
PLUGIN_MIGRATION_DROPS_CREATED_SCHEMA | 409 | nextly migrate:create --plugin would drop a table or column that the plugin's earlier migrations created, which loses its rows. A rename comes out as a drop and an add. The message names each; nothing is written and the command fails. | Write the rename, or the deliberate drop, by hand in a module from nextly migrate:create --plugin <entry> --blank, which records the change for your SQL. |
PLUGIN_MIGRATION_ADDS_UNFILLABLE_COLUMN | 409 | nextly migrate:create --plugin would add a NOT NULL column with no default to a table the plugin's earlier migrations created, and the rows already in it would have no value for it. Nothing is written. | Give the column a default, or add it nullable, fill the rows and make it NOT NULL by hand in a module from nextly migrate:create --plugin <entry> --blank. |
PLUGIN_MIGRATION_SQL_MISSING | 409 | nextly migrate reached a plugin module that changes the schema on this dialect but has no statements for it: a module written for its author's SQL that was never filled in. Nothing is applied. | Write the module's up and down for that dialect, then run nextly migrate again. |
Migrations
These come from nextly migrate, migrate:down, and the boot's migrations. See Production migrations.
| Code | Status | Cause | Fix |
|---|---|---|---|
INVALID_INPUT | 400 | A migration file or plugin module holds a statement the runner refuses, and nothing in it ran. logContext.refusals lists a code per statement: TRANSACTION_CONTROL_IN_MIGRATION, SESSION_SETTING_IN_MIGRATION, NOT_TRANSACTIONAL_IN_MIGRATION, or NEEDS_TRANSACTION_IN_MIGRATION: a unit marked to run outside a transaction (-- nextly:no-transaction, or transaction: false on a module) holds its own BEGIN, START TRANSACTION, COMMIT or END, a savepoint, or PostgreSQL's SET LOCAL, SET CONSTRAINTS or SET TRANSACTION, which need one. (On SQLite such a unit writing PRAGMA foreign_keys or PRAGMA defer_foreign_keys is refused as SESSION_SETTING_IN_MIGRATION.) | Edit the unit as the message says; for NEEDS_TRANSACTION_IN_MIGRATION, move the statement to a file without the marker or a module without transaction: false. |
NEXTLY_MIGRATION_PARTIALLY_APPLIED | 500 | A unit marked to run outside a transaction failed part-way: the message names the failing statement and how many before it stayed applied, and the database's own error is in the cause. Also raised by nextly migrate for such a unit whose newest attempt is that failure, or an attempt that never finished because the process running it stopped (its ledger row still in_progress), and on MySQL for any unit whose newest attempt failed or never finished (MySQL commits each schema statement as it runs, even in a transaction), rather than recording it applied without running it or running it again over what stayed. logContext.reason is partially-applied. | Finish its remaining statements by hand, then record it: an app file with nextly migrate:resolve --applied <file> (a file with no snapshot is recorded without comparing the live schema when it is marked, or on MySQL after an attempt that failed or recorded no outcome), a plugin module with nextly migrate:resolve --failed-cleanup plugin:<name>/<module> and then nextly migrate. Or reverse the statements that ran, clear the attempt with nextly migrate:resolve --failed-cleanup <file>, and run nextly migrate again. For a DOWN, finish or reverse its statements by hand before running it again. |
NEXTLY_MIGRATION_FOREIGN_KEY_VIOLATION | 409 | SQLite only. A unit left new rows referencing rows that do not exist (logContext.reason is dangling-reference), or foreign-key enforcement could not be switched off because another transaction was open (enforcement-still-on, nothing applied). A unit run in a transaction is rolled back. A unit marked to run outside one keeps its statements and is recorded as failed. | Fix the migration and run it again. For a unit run outside a transaction, repair or remove the rows the message names, then mark it applied as for NEXTLY_MIGRATION_PARTIALLY_APPLIED. For enforcement-still-on, run it again once the other transaction has finished. |
NEXTLY_MIGRATION_CONCURRENT_RUN | 409 | Another run recorded the same migration applied, or rolled it back, while this one was running it. Where the transaction can undo the work, this run's statements were rolled back with its ledger write, and the ledger keeps the other run's record. For a unit marked to run outside a transaction, or on MySQL, the statements may have stayed applied, and the attempt is recorded as failed. logContext.reason is concurrent-run. | Run nextly migrate:status: the migration is already applied, or rolled back, by the other run. Where the message says the statements may have stayed applied, check what the migration changes before going on, then record it as for NEXTLY_MIGRATION_PARTIALLY_APPLIED. |
Plugin data access
These are thrown to the plugin code that made the call, not at boot.
| Code | Status | Cause | Fix |
|---|---|---|---|
INVALID_INPUT | 400 | transaction was called on the handle ctx.db.transaction passes its work (logContext.reason is nested-plugin-transaction). | Do the nested work in the same callback, through the handle it was given. |
VALIDATION_ERROR | 400 | A ctx.services.collections.*InTransaction method was passed something other than the token withTransaction handed the work (logContext.reason is plugin-transaction-token-unknown). | Pass the tx your withTransaction callback received. |
VALIDATION_ERROR | 400 | A transaction was used after its callback settled: the tx of ctx.db.transaction or ctx.db.raw.transaction, or the token withTransaction handed its work, kept and called later (logContext.reason is plugin-transaction-finished). | Do the work inside the callback, before it returns, and await it there. |
Permissions
| Code | Status | Cause | Fix |
|---|---|---|---|
NEXTLY_PERMISSION_COLLISION | 409 | A custom permission duplicates another, targets a reserved system resource, or reuses an auto-seeded CRUD (action, resource). logContext.reason ∈ duplicate-permission, system-resource-reserved, crud-permission-reserved. | Choose a unique (action, resource); don't redeclare CRUD permissions (they're auto-seeded). |
Routes
| Code | Status | Cause | Fix |
|---|---|---|---|
NEXTLY_ROUTE_COLLISION | 409 | Two routes share the same (method, full path) after namespacing under /plugins/<name>. | Give each route a distinct method/path. |
NEXTLY_ROUTE_INVALID_PATH | 400 | A route path does not start with /. | Start the path with / (e.g. /export). |
Dashboard widgets
| Code | Status | Cause | Fix |
|---|---|---|---|
NEXTLY_PLUGIN_REMOVED_WIDGET_CHANNEL | 500 | A plugin, enabled or not, carries contributes.admin.widgets or contributes.widgetSources, which Nextly no longer reads. logContext.plugin names the plugin and logContext.key the key. | Declare each widget with defineWidget under contributes.dashboard.widgets, and read its data in that widget's load. |
Requests
| Code | Status | Cause | Fix |
|---|---|---|---|
VALIDATION_ERROR | 400 | A request carrying the refresh cookie (an /admin/api/auth/* request from a signed-in browser) is handed to an auth hook, a strategy or a plugin route with the cookie removed, and its body, not yet read by anything, is over 64 KiB: the cookie-free copy reads at most that much, and refuses the rest with the error code too_large in errors[].code and logContext.reason body-too-large. A body the handler has already read, as core login reads its own, is not read again. (A csrf route option's reader has the same cap, and reports an oversized body as the CSRF refusal instead.) | Send a body of at most 64 KiB to auth routes. |
Inspecting plugins
Use the CLI to see what's installed and detect issues without booting the app:
nextly plugins list # table of plugins + contributions
nextly plugins info <name> # one plugin's detailsA resolution error surfaces here too (the commands run the same validation).