Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

Strapi on Heroku stops with: Middleware strapi::session App keys are required

ErrorMiddleware "strapi::session": App keys are required

Short answer

Strapi requires app.keys in config/server.js, and the session middleware uses them. On Heroku your local .env is not there, so APP_KEYS is empty. Set APP_KEYS as a comma-separated config var with heroku config:set, and make sure config/server.js reads it with env.array('APP_KEYS').

  • Applies to Strapi 5, Node.js 22, Heroku CLI
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    List the config vars Heroku holds for the app. If APP_KEYS is not in the list, the deployed process has no keys at all.

    heroku config --app my-strapi-app
  2. 2Match what you see, then jump to its fix

    1. 1heroku config shows no APP_KEYS lineAPP_KEYS is not set on the platformFix
    2. 2APP_KEYS is set on Heroku and the same error remainsconfig/server.js does not read the keysFix

What does the error look like?

  • Middleware "strapi::session": App keys are required
  • The app boots locally but crashes on Heroku at start

Cause 1 of 2

APP_KEYS is not set on the platform

1Check

Strapi's deployment guide says to inject secrets from your platform or CI and never from a committed .env file, and lists APP_KEYS among the secrets the build and the server both need. A .env that lives only on your laptop never reaches the dyno.

heroku config:get APP_KEYS --app my-strapi-app
grep APP_KEYS .env

2Fix

Copy the APP_KEYS value your local .env already has (the Strapi CLI generated it at project creation) into a Heroku config var. Keys are separated by commas. Quote the pair so the shell keeps it intact.

heroku config:set 'APP_KEYS=key1==,key2==,key3==,key4==' --app my-strapi-app

3Verify

Setting a config var restarts the app. Watch the logs for a clean boot.

heroku logs --tail --app my-strapi-app

Confirmed by docs.strapi.io

Did this fix it?

Cause 2 of 2

config/server.js does not read the keys

1Check

app.keys is a mandatory server option with no default, and it must be an array of strings. Open the server config and see whether the app block is there.

cat config/server.js

2Fix

Add the app block that maps the environment variable to the array. Use config/server.ts in a TypeScript project, and rebuild the admin panel after you change it.

module.exports = ({ env }) => ({
  host: env('HOST', '0.0.0.0'),
  port: env.int('PORT', 1337),
  app: {
    keys: env.array('APP_KEYS'),
  },
});

3Verify

Rebuild, commit and deploy, then check the process starts.

npm run build
git push heroku main

Confirmed by docs.strapi.io

Did this fix it?

How do I stop it coming back?

  • Keep one set of APP_KEYS per environment and reuse it across deployments; regenerating secrets invalidates existing sessions and API tokens.
  • Never commit the .env file; load secrets through the platform's config vars.
  • After any config var change, remember Heroku restarts the app and creates a new release.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Back end

ng serve says it cannot determine the project or target

Cannot determine project for command.

The Angular CLI looked through angular.json for a project that defines the target you asked for (serve, build, test) and found none, or found several and could not pick one.

3 causes, each with a fix

Back end

ng serve cannot find the dev-server builder package

Could not find the implementation for builder @angular/build:dev-server

The builder named in angular.json (for example @angular-devkit/build-angular:dev-server) is looked up as an npm package starting from the workspace root.

3 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.