Find the error. Get your app running.

Start with the first failing stage: installing dependencies, building, starting the process, or reaching the public URL. A generic “deployment failed” message tells you less than the first specific error in the logs.

These steps use hosted ForgeVPS's GitHub deployment workflow. Open your machine, select the app under Servers, and check Deployments for build output or Logs for the running process. Record the failed commit and the first relevant error before retrying.

The install command fails

npm ci reports a missing or mismatched lockfile

Check that the repository contains package-lock.json and that it matches package.json. In your source project, run npm install, review the resulting dependency changes, then commit and push both files. Keep deployment installs repeatable with npm ci.

If you use pnpm or Yarn, use that project's package manager and lockfile instead. Do not generate a second lockfile just to silence an error. The npm ci documentation explains why it refuses to rewrite an inconsistent lockfile.

The runtime or package manager is missing

A “command not found” error is different from a dependency error. Check the machine's setup status and the runtime required by the project. From Terminal, node --version and npm --version identify the available Node tools. Compare them with the project's documented requirements and the deployment output.

If GitHub access fails before installation, check that the repository still exists, the connected branch is correct, and the ForgeVPS GitHub app still has access to it.

The build fails

Open the failed deployment and read the first compiler, type, or syntax error. Fix that file in the source project using the code editor, run the same build command there, and commit the correction. An assistant can help explain the error; give it the relevant error and code without copying secrets from environment files.

If the log says “Missing script: build,” inspect package.json. The configured build command must match a real project script. A plain Node app may only need a syntax check; a Next.js app needs its production build. The reference app walkthrough shows a complete working set of commands.

For an out-of-memory error or a process abruptly reported as “Killed,” check machine memory and concurrent builds. “Killed” alone does not prove memory exhaustion. Correlate it with machine or operating-system logs before changing capacity or application settings.

The build succeeds, but the app stops

Switch to Logs. A build artifact can be valid while the start command immediately fails. Check that the production start script exists, references files the build actually created, and keeps the web process running.

The log says EADDRINUSE

Check the port shown for this app and the port it actually attempts to use. Read process.env.PORT instead of hardcoding 3000. Check for a development process still using the same port. The multiple-app guide explains how to give every app its own address.

A configuration value is missing

Open Env and check the variable's name and value. Save, then redeploy. ForgeVPS links the file into the release as .env; the application must load it. The reference Node app uses an explicit environment-file flag. Your framework may load it automatically or require a different setup.

Some framework values are compiled into browser assets during the build. Changing only the running process cannot replace those compiled values. Follow the framework's build-time rules, and never put a secret in a variable intended for browser code.

The app runs, but the URL fails

Separate the app from the public route. In the VPS terminal, request a known app endpoint on its assigned port. Replace 3000 below with the port shown in ForgeVPS:

curl --max-time 10 -i http://127.0.0.1:3000/

• Connection refused: check the process, listening address, and port. A domain change will not start a stopped app.
• An HTTP response: the local app is reachable. A 404 may just mean the requested route does not exist; try a known route.
• The local request works, but the domain gives 502: check the app's assigned port and domain mapping. Caddy may be unable to reach the expected upstream.
• The domain times out or HTTPS fails: verify DNS, including stale AAAA records if present, and that ports 80 and 443 reach the VPS through both firewalls.

In Domains, use Check DNS and confirm the hostname belongs to this app. If you use a DNS proxy, its behavior can affect the checks; consult its settings as well. Caddy's HTTPS requirements cover certificate validation and reachability.

Do not disable the entire firewall as a troubleshooting shortcut. Check the specific route or port that should be reachable.

Recover, then verify the fix

If a previously working commit is compatible with the current data and configuration, open its menu in Deployments and choose Roll back to this commit. ForgeVPS rebuilds that commit, so its dependencies and build still need to work.

Rolling back code does not undo a database migration or restore an older environment file. Check compatibility first. Database recovery is a separate operation; use the PostgreSQL restore guide when the data itself needs recovery.

After a fix, check the new deployment, running logs, and public URL. Test the feature that failed, including a database-backed action if relevant. A green build plus a working real request is stronger evidence than repeatedly clicking deploy.