Skip to content
Stackpad Docs

Troubleshooting

This page covers the most common issues you might run into on Stackpad and how to resolve them.

Build failures

”Build timed out”

Builds have a 10-minute timeout. If your build exceeds this:

  • Large node_modules: Check if you have unnecessary dependencies. Remove unused packages from package.json
  • No lockfile: Without a lockfile (pnpm-lock.yaml, yarn.lock, or package-lock.json), every install resolves dependencies from scratch. Commit your lockfile
  • Monorepo installs: Monorepo workspace installs can be slow. Ensure your lockfile is up to date and committed
  • Heavy build step: If your build compiles a lot of code (large Next.js sites, many pages), consider incremental builds or reducing page count

”TypeScript errors”

Your code doesn’t compile. Stackpad runs the build command from your package.json, which typically runs tsc or your framework’s build.

Fix: Run npm run build locally first. Fix all errors before pushing. Stackpad’s build environment matches a standard Node.js environment.

”Module not found”

A dependency is missing or not installed.

  • Check that the module is listed in package.json dependencies (not just devDependencies if it’s needed at runtime)
  • For monorepos: check that the root directory is set correctly in the service settings
  • Make sure your lockfile is committed and up to date

”Cannot find next.config.js” (or similar)

The root directory is wrong. If your app is in a subdirectory (e.g. apps/web in a monorepo):

  1. Go to the service settings
  2. Set the Root directory to the correct path (e.g. apps/web)
  3. Redeploy

Deployment failures

”Health check failed”

The build succeeded but your application didn’t respond within 90 seconds of starting.

Common causes:

  1. Missing environment variable — your app crashes on startup because a required variable (like DATABASE_URL) isn’t set

    • Check: Go to service Env Vars tab and verify all required variables are present
    • If you just added a database, you need to redeploy the web service to pick up DATABASE_URL

  2. Port mismatch — your app listens on a different port than what’s configured in Stackpad

    • Check: Verify the port in your service settings matches what your app actually listens on
    • Next.js default: 3000, Astro: 4321, Express: 3000 (unless you configured differently)

  3. Application crash — your app throws an error on startup

    • Check: Look at the service Logs tab — if the container started briefly before the health check failed, it may have logged the error

  4. Slow startup — your app takes longer than 90 seconds to start

    • Check: Run your app locally and time how long startup takes
    • Fix: Move slow operations (migrations, data loading) to the build step instead of startup

”Deployment rolled back”

This means the health check failed and Stackpad restored the previous version. Your users weren’t affected — the old version continued serving traffic.

To debug:

  1. Click the failed deployment in the Deployments tab
  2. Read the build logs — look for errors near the end
  3. Check the service Logs — look for runtime errors

Connection issues

”Can’t connect to database”

If your app logs connection errors for PostgreSQL, MariaDB, or Redis:

  1. Check DATABASE_URL exists — go to service Env Vars tab and look for it (with lock icon)
  2. Recently added database? — you need to redeploy the web service after adding a database service
  3. Correct hostname — use postgres (not localhost or an IP). The private network DNS resolves service names automatically
  4. Database is running — check the database service status in the dashboard. If it shows “Stopped”, it may have crashed

”ECONNREFUSED on localhost”

Your app is trying to connect to localhost instead of the service name.

Fix: Use the auto-injected DATABASE_URL or REDIS_URL environment variables. Don’t hardcode localhost — on Stackpad, each service runs in its own container, so localhost only refers to the service’s own container.

// Wrong
const pool = new Pool({ host: 'localhost', port: 5432 });


// Correct
const pool = new Pool({ connectionString: process.env.DATABASE_URL });

Domain issues

”DNS not verified”

After adding a custom domain, Stackpad needs to verify your DNS configuration. This can take time:

  • Stackpad checks DNS every 5 minutes
  • DNS propagation can take up to 48 hours (though usually much faster)
  • Verify your DNS record is correct: use dig your-domain.com CNAME to check

”HTTPS certificate not issued”

Certificates are issued automatically via Let’s Encrypt after DNS verification. If verification succeeded but you still see certificate errors:

  • Wait a few minutes — certificate issuance takes 1-2 minutes after DNS verification
  • Check that no other service (like Cloudflare proxy) is intercepting traffic. If using Cloudflare, set the DNS record to DNS only (gray cloud), not Proxied (orange cloud)

Next.js specific

”Large deployment size”

Without standalone mode, Next.js includes the entire node_modules in the deployment.

Fix: Add output: 'standalone' to your next.config.js:

const nextConfig = {
  output: 'standalone',
};


export default nextConfig;

This creates a minimal production bundle that starts faster and uses less memory.

”NEXT_PUBLIC_* variables not working”

NEXT_PUBLIC_* variables are embedded into your JavaScript bundle at build time. If you change them:

  1. They must be set as environment variables in Stackpad before the build
  2. Changing them requires a rebuild — runtime changes don’t affect the already-compiled JavaScript

Environment variable issues

”Variable changed but app still uses old value”

Environment variable changes don’t automatically trigger a redeploy. The running container keeps the old value.

Fix: Click Redeploy on the service after changing variables.

”Variable set at project level but service uses different value”

Stackpad has three scoping levels that override each other:

Project → Environment → Service

A service-level variable overrides an environment-level variable, which overrides a project-level variable with the same key. Check all three levels in the dashboard.

Still stuck?

If you can’t resolve the issue: