Troubleshooting

Start with the deployment page: the failed step and the build log almost always name the cause. The cases below account for most support requests.

"Pre-checks failed": no supported app type

Vinssi found a package.json but none of the detection rules matched.

• Next.js and Vite projects need their config file, next.config.* or vite.config.*, in the root directory. Add one even if it is empty.
• Node backends are detected by a dependency on express, fastify, hono or @nestjs/core. A server built on another framework can be deployed by adding one of those as a dependency, even unused, until broader detection ships.
• In a monorepo, set Root directory to the folder that holds the app's package.json.

"Couldn't prepare": install or build failed

Read the log. Common causes:

• Frozen install failed. The lockfile does not match package.json. Run your package manager locally, commit the lockfile, push.
• Build script exited with an error. The same error should reproduce locally with npm run build on Node 22. Type errors that your editor tolerates will fail here.
• A tool is missing. The build container has Node 22, npm, git and network access, nothing else. Install what you need in the build command, for example npx prisma generate && npm run build.
• Out of memory. Builds have 4 GB. Reduce parallelism or split the build.
• Timed out. Builds are limited to 25 minutes.

"Publish failed": the app never started listening

The build succeeded but nothing accepted connections on port 3000 within about two and a half minutes. Runtime output is not available in the dashboard yet, so work from these checks:

1. Port. The server must listen on process.env.PORT, which is 3000. A hardcoded 8080 or localhost-only bind is the most common cause.
2. Start command. Next.js apps are started with next start. Node backends run your start script through npm, or node dist/index.js if there is none. Check that the file the command points at exists after the build.
3. Crash on startup. Apps that connect to a database or read required configuration at startup exit immediately when a variable is missing. Compare Settings → Variables with your .env.example; DATABASE_URL is the usual gap. Either add a managed database, which injects it for you, or set the variable. Remember variables only apply to deployments created after you set them, and a managed database that is still provisioning is not injected until it is ready.
4. Reproduce locally. Run the built app with PORT=3000 and the same variables. If it fails locally, the log there is the log you need.

"Issue detected" after being live

The app stopped answering on port 3000. Vinssi does not restart it. Typical causes are an unhandled exception that exits the process, or exceeding the plan's memory ceiling. Deploy again to restart; if it recurs, add a process-level error handler and check memory use against the plan.

A push did not deploy

Nothing appears under Deployments after a push. One of these applies:

• The push was to a branch other than the repository's default branch, or was a tag.
• The project has no active plan, or payment is past due. See the banner on the project page.
• The project is deactivated or scheduled for deletion.
• The GitHub App installation was suspended or removed. Reinstall from the dashboard.
• The commit was already deployed to this project.

Variables did not change anything

Variables are packaged into a deployment when it starts. Trigger a new deployment after changing them.

Domain verification keeps failing

• The TXT record must be at _vinssi-challenge.<your hostname>, not at the hostname itself. Some DNS providers append the zone automatically; enter only _vinssi-challenge or _vinssi-challenge.app in that case.
• Copy the value exactly, including the vinssi-domain-verification= prefix.
• Wait. Propagation takes minutes to an hour depending on the provider. The error message repeats the exact record Vinssi looked for.
• The CNAME does not affect verification, but without it the domain will not serve traffic once verified.

vinssi login does not open a browser

Copy the URL the command prints into any browser where you are signed in to Vinssi. The request expires after five minutes; run the command again if it does. On headless machines, create a token from a laptop with vinssi tokens create and set VINSSI_TOKEN instead.

Node version override has no effect

That is expected today: builds and runtime use Node 22 regardless of engines, .nvmrc or the build setting. The declared version is recorded for reference only.

Still stuck

Email cloud@vertics.co with the project name and the deployment id from the URL. Include the last lines of the build log.