Build and deploy troubleshooting

Start with the build log of the failed deployment and read it from the top: the first error is usually the cause. The first lines also show what the builder detected; if that is wrong, the rest will be too.

The app crashes at boot: missing NUXT_* variables

Symptom: the build succeeds, then the deployment ends as crashed. The runtime log shows an error from your app about a missing or empty setting, typically thrown by code that reads useRuntimeConfig() or process.env on startup.

Cause: Nuxt reads runtimeConfig overrides from NUXT_* environment variables when the server starts (NUXT_API_SECRET overrides runtimeConfig.apiSecret, NUXT_PUBLIC_API_BASE overrides runtimeConfig.public.apiBase). If they are only in your local .env, the production server starts without them. .env files are not read by node .output/server/index.mjs.

Fix: add every NUXT_* variable the app needs in the service's Variables tab. Saving redeploys the service. Values you read with process.env.X inside nuxt.config.ts are evaluated at build time instead; Fjordrun passes variables to the build as well, so the same variables cover both.

stream did not contain valid UTF-8 and other errors from ._ files

Symptom: a build tool fails on a file whose name starts with ._, for example stream did not contain valid UTF-8, or a bundler cannot parse ._index.vue.

Cause: macOS writes AppleDouble metadata files (._name) and .DS_Store when files are copied to some external drives or network shares. They are binary and break tools that read every file in a folder.

Fix: none needed: the builder deletes them before every build and logs Removed N macOS metadata file(s) (._* / .DS_Store). To keep them out of your repository, add ._* and .DS_Store to .gitignore and remove the committed ones with git rm --cached.

Node 18: styleText

Symptom:

SyntaxError: The requested module 'node:util' does not provide an export named 'styleText'

Cause: the project pins Node.js 18 (in engines.node, .nvmrc, .node-version or .tool-versions), but a current tool (recent Vite, Nuxt, Astro, their CLIs or dependencies) needs Node.js 20.12 or newer.

Fix: pin a current LTS, for example "engines": { "node": ">=22" } or 22 in .nvmrc. Without a pin, Fjordrun uses Node.js 22. See Node.js version.

Vite preview: Blocked request. This host is not allowed

Symptom: the site answers with

Blocked request. This host ("web-production-3f2a.fjordrun.app") is not allowed.
To allow this host, add "web-production-3f2a.fjordrun.app" to `preview.allowedHosts` in vite.config.js.

Cause: the container runs vite preview (or a script that calls it). vite preview is a local preview server that rejects unknown host names. It is not meant for production.

Fix: let Fjordrun serve the build. The builder ignores a start command that only runs a preview or dev server (vite preview, nuxt preview, astro preview, npm run preview, npm run dev...) and serves static output with nginx or runs the framework's production server. Clear the start command in Settings → Deploy. If your own Dockerfile runs vite preview, serve dist/ with nginx instead (see the Docker guide).

The build ran out of memory

Build ran out of memory (512 MB plus swap) — reduce what the build loads at once, upgrade to Pro for 1 GB builds, or build the image in CI and deploy it

See Build resources.

Lockfile out of date

npm ci can only install packages when your package.json and package-lock.json or npm-shrinkwrap.json are in sync.

or ERR_PNPM_OUTDATED_LOCKFILE with pnpm, or The lockfile would have been modified by this install, which is explicitly forbidden. with Yarn Berry.

Fix: run the install locally, commit the updated lockfile and push.

Nothing to run

Found package.json but nothing to run: add a `start` script (e.g. "node server.js"), a `main` entry, or a `build` script that outputs a static site, or set a start command in Settings.

The builder found no framework, no start script, no main entry, no server.js/index.js and no build script. Add one of those, or set a start command.

Unsupported adapter

Astro is configured with the @astrojs/vercel adapter, whose output only runs on that platform. Use @astrojs/node (mode: 'standalone') for a server, or remove the adapter for a static site.

SvelteKit uses @sveltejs/adapter-auto, which can't produce a build Fjordrun can run. Install @sveltejs/adapter-node (server) or @sveltejs/adapter-static (static site) and set it as the adapter in svelte.config.js.

Switch to the adapter the message names. See the Astro and SvelteKit guides.

The deployment never becomes ready

Symptom: the build succeeds, the deployment stays in deploying and then fails; the runtime log shows the app started.

Cause: the app listens on localhost / 127.0.0.1, or on a different port than the service's Port (default 8080), so Fjordrun cannot reach it. Or a healthcheck path is set that does not return a success status.

Fix: listen on 0.0.0.0 and process.env.PORT (or $PORT), or set Port to the port your app uses. Check the healthcheck path in Settings → Deploy.

The custom start command is ignored

The build log says so, for example:

note     custom start command `npm run preview` runs a preview/dev server; using node .output/server/index.mjs instead — clear it in Settings

or, for a static site, Static site: served by nginx on $PORT; the custom start command is ignored. This is intentional; see Start command.

Still stuck

Email support@fjordrun.com with the project, service and the deployment's time. Check status.fjordrun.com for platform incidents.