nextjs checks SERVER ONLY env variables during build (why?)

[sznski]

I'm encountering an issue when running a Docker build in a GitHub Action for my Next.js 15.0.3 application. The build process runs without any .env files, yet certain routes that require environment variables are being initialized unexpectedly. This results in errors during the build, such as:

#18 85.26 [ioredis] Unhandled error event: RangeError: Port should be >= 0 and < 65536. Received type number (NaN).
#18 85.28 Error: [@octokit/webhooks] options.secret required

Here’s a snippet of the relevant log:

#18 2.383    ▲ Next.js 15.0.3
#18 2.397    Creating an optimized production build ...
#18 85.26 [ioredis] Unhandled error event: RangeError: Port should be >= 0 and < 65536. Received type number (NaN).
#18 85.28 Error: [@octokit/webhooks] options.secret required

The errors appear because:

1. Redis expects a valid port number from an environment variable.
2. The GitHub Webhook route expects a secret key to be provided.

These routes are dynamic and shouldn’t be initialized during the build phase. In my setup, I use Kubernetes to build and deploy, where secrets are injected as environment variables at runtime, not during the build process.

While I understand that I could provide default values for the Redis port or webhook secret (e.g., 6379 or "verysecret"), this approach feels unintuitive and potentially insecure.

[icyJoseph]

Unfortunately, Next.js loads the module to do some checks, and because of how Modules work in JS, any top level code is executed, and that's where things might be going south for you.

Often you can wrap your top level code under an initializer function, and execute that function within your route handlers, or page rendering. Saving to a top level variable clients, and other objects you might want to reuse later on.