Build Fails Due to Missing Database Connection

[musti17]

🐛 Issue: Build Fails Due to Missing Database Connection

Description

The website template of Payload fails to build unless a database connection is provided or a container is running. This contradicts the Payload migration docs, which state that the build process should not require a database connection. Quoted as "Running them during build time may be impossible due to not having access to your database connection while building or similar reasoning."

Expected Behavior

The build should complete successfully without requiring an active database connection.

Current Behavior

• Running npm run build (or equivalent build command) fails unless a database is connected.
• The error suggests that the application is attempting to connect to the database during build time.

Steps to Reproduce

1. Clone the Payload website template.
2. Ensure no database is running.
3. Run npm run build.
4. Observe the error related to the missing database connection.

Additional Context

This behavior is unexpected based on the documentation. If this is intentional, it should be explicitly mentioned in the docs. Otherwise, a fix is needed to allow builds to run without a database connection.

[simovicaleksa]

Any movement on this?

[hades200082]

Issue filed at #12605

[Borcsa134]

I saw that there is a solution added to the docs now, but I am not happy with that. Since this issue can occur in production as well (db is unreachable for any reason) it would be nice to be able to handle this exception in like a middleware or something.

[musti17]

Hi @musti17, I've just hit on this issue, would you mind expanding on the compile mode please? if it's still a vaild bypass.

Hey @pas-mike — yeah, it's still a valid workaround but comes with trade-offs.
Using compile mode essentially disables Static Site Generation (SSG), so all pages are rendered on the server at request time. This avoids the DB connection requirement during the build step, but also means you're giving up many of Next.js's performance benefits like pre-rendering and static optimization.
To retain those SSG benefits, you'd have to use next build & the experimental generate mode before starting the app. However, the downside there is that it prevents generating a fully standalone image — meaning your Docker image can end up significantly larger.
So really, it's a trade-off between build-time flexibility and runtime performance + image size. Hopefully the Payload team addresses the root issue soon.

[musti17]

Attaching an issue which helped me in this problem for current and future references: vercel/next.js#46544

[hades200082]

Compile mode solves my issue which was that I wanted to use a GitHub action to verify the build and run tests on PRs.

The database requirement made this impossible so compile solves it. That's the CI part.

For CD a database will always be required for SSG, and that's ok.

[filecage]

I also stumbled upon this when my build failed during docker build because of the missing database connection and dug a bit into the database packages. While this is something you could workaround by disabling the SSG (which is not a good workaround in my opinion), it is still concerning that my whole app would crash unrecoverably once the database becomes unreachable for whatever reason (in my use case, only a small portion of my site uses Payload and thus requires a database connection - but also if a bigger portion of my site relies on a database connection, I'd rather handle that error gracefully with a custom error page or similar).

I opened a discussion in #13537 about changing the behaviour of the database packages so they don't exit the nodejs process on a database failure.