"Invalid APP_KEY" error after a failed AdonisJS 5 upgrade — safe recovery path for app and migrations

1. Correct Recovery Sequence

When an upgrade stops midway, the first thing that blocks the application is the Invalid APP_KEY error. The framework cannot decrypt any encrypted values, so the server never reaches the migration layer. Therefore the safe order is:

1. Restore a valid APP_KEY in .env (or config/app.ts if you generated a key with node ace generate:key).
2. Verify that the application can start: node ace serve should run without the key error.
3. Once the app is bootable, inspect the migration state: node ace migration:list or node ace migration:status.
4. Identify any partially applied batches and roll them back.
5. Re‑run the pending migrations.

Attempting to rollback before the app can start is risky because the CLI commands rely on a working database connection that is established during boot. If the APP_KEY is invalid, the database connection may still succeed, but any encrypted configuration values (e.g., JWT secret) will be unusable. Fixing the key first guarantees that all subsequent commands run in a consistent environment.

2. Identifying and Undoing a Partial Migration Batch

AdonisJS stores the migration history in the migrations table. Each applied migration is recorded with a batch number. A partially applied batch appears as a set of rows that were inserted but whose corresponding migration file never finished executing.

To locate it:

# List all migrations with their batch numbers
node ace migration:list

Look for a batch that contains fewer rows than the number of migration files that share the same timestamp directory. The batch column will show the same number for all rows in that group.

Once identified, roll back that specific batch:

# Replace  with the number you found above
node ace migration:rollback --batch=

This command will:

• Execute the down method for each migration in that batch.
• Delete the corresponding rows from the migrations table.
• Leave the rest of the database untouched, so existing data remains intact.

After the rollback, verify that the migrations table no longer contains the batch rows:

node ace migration:list

Finally, re‑run the pending migrations:

node ace migration:run

All remaining migration files will be applied in the correct order.

3. Built‑in Consistency Checks

AdonisJS 5 does not ship a pre‑startup consistency validator that compares the migration table against the filesystem. The framework only reports migration status via the CLI. Therefore, before restarting the server you should manually confirm that the migration table matches the set of migration files:

1. Run node ace migration:list and ensure that every file in database/migrations appears as either Pending or Applied.
2. If the table is missing entries or contains orphan rows, you may need to manually insert or delete rows in the migrations table, or use node ace migration:rollback --force to correct the state.

Once the migration state is verified, the application can be started normally without encountering the Invalid APP_KEY error.