Preview environment troubleshooting: Common failures and how to fix them
A preview environment can fail before it exists, build successfully but never become ready, or look healthy while the feature under review is still broken. The visible error is often several steps away from the actual problem.
For larger engineering organisations, the challenge is not only fixing one failed preview. Teams may need to trace the same pull request across CI, Kubernetes, infrastructure code, cloud networking, secret managers, and observability tools. A repeatable troubleshooting path reduces that operational overhead and gives every team the same place to start.
This guide walks through the most common preview environment failures, what to check first, and how to confirm that the fix worked.
Work through the preview in dependency order: trigger, blueprint run, build, container, health checks, networking, configuration, data, updates, and cleanup.
- Confirm that the Git event matched the trigger and find the first failed step.
- Check that the expected commit produced a successful build.
- Inspect container logs, health checks, networking, and resource usage.
- Check runtime variables, secrets, database connections, migrations, and callbacks.
- Reproduce the problem, then confirm that the preview updates and deletes correctly.
Northflank Preview Environments can create full-stack environments for pull requests, including services, databases, and jobs. You define the environment once with a reusable Preview Blueprint.
If a preview fails, Northflank provides logs and metrics for builds, deployments, jobs, and addons, so you can follow the failure across the environment.
Get started with Northflank self-serve, or book a demo to discuss your preview workflow.
Start with the earliest stage that did not produce the expected result. A preview URL returning 502 may be caused by routing, an unready container, a crash, or a build that never completed. Changing the route first will not fix a missing image.
If no preview was created, check the trigger before the application.
Make sure the trigger watches the correct repository and event. Then check its branch rules, pull-request rules, path filters, required labels, check-suite requirements, and commit-message ignore flags. The trigger may be working correctly but excluding the change.
To separate a trigger problem from an environment-definition problem, you need a way to test the same preview without waiting for another Git event. Northflank Preview Blueprints support pull-request, push, GitHub check-suite, PR-label, webhook, and API triggers, and can also run manually against a selected commit. If the manual run succeeds, focus on the trigger and repository integration. If it fails, inspect the blueprint run.
Check the fix: create a small change that matches the trigger rules and confirm that it creates one preview for the expected commit.
A preview cannot deploy the new application image if its build did not finish.
Open the build for the expected commit and find the first useful error. The final line may only say that a command exited unsuccessfully.
Common causes include:
- An incorrect Dockerfile path or build context
- Files excluded by
.dockerignore - Dependency or lockfile errors
- Missing credentials for a package registry, submodule, or base image
- A value supplied at runtime when the build needs it as an argument
- Insufficient build resources
When a pull request has several commits or rebuilds, first confirm which artifact the preview tried to deploy. On Northflank, build history shows the branch, commit hash, duration, status, logs, and metrics for each build. If you use a Dockerfile, compare its location, context, target stage, and credentials with the documented Dockerfile build options.
A preview can create some resources before a later blueprint step fails. Start with the first failed step; later steps may simply be waiting for an output that does not exist.
Check for invalid configuration, missing permissions, unavailable resources, name conflicts, or a reference that was resolved too early. A service URL or database connection value is not available until the resource that produces it is ready.
Templates that pass generated URLs or connection details between resources must wait until those values exist. For this reason, Northflank recommends confirming that the resource is running before using a dynamic DNS or addon reference.
Start with the logs from the first terminated container. Later restarts may show secondary errors that hide the original cause.
Look for an invalid start command, missing runtime variable, incompatible binary, failed import, file-permission problem, or unavailable dependency. Compare the exit with CPU and memory usage. An out-of-memory termination needs a different fix from an application exiting because a variable is missing.
Diagnosing a restart is easier when the process failure and its surrounding resource usage are visible together. Northflank's container monitoring shows running and terminated containers with logs, metrics, and health-check results, while the log viewer covers builds, deployments, jobs, and addons. You can also access a shell for a running service or job container.
A running process is not automatically ready to receive traffic. An incorrect readiness probe can keep a healthy container out of the load balancer.
Check the probe's protocol, path, port, command, delay, timeout, and failure threshold. Test the exact endpoint or command inside the container. If startup time varies, use a startup probe to delay readiness and liveness checks.
To understand why a running container is not serving requests, you need the result of the exact probe controlling its state. Northflank supports HTTP, TCP, and command-based health checks, with separate startup, readiness, and liveness behavior for traffic and container replacement.
Test the connection from the inside out:
- Confirm that the application listens on the expected container port.
- Call the service through its private endpoint.
- Call the generated public URL.
- Test any custom domain, path rule, authentication, or IP policy.
If the first test fails, the application may listen on the wrong port or bind only to 127.0.0.1. Containerised applications commonly need to listen on 0.0.0.0; Northflank's application exposure guide shows how application binding and port configuration fit together.
If private access works but public access fails, the problem has narrowed to the external route or its access controls. Northflank's networking documentation covers public endpoints, private ports, domains, and network security, so check whether the correct port is public, whether the domain or path points to it, and whether an authentication or IP policy blocks the request.
A working homepage does not prove that the complete feature works. The frontend may call a shared API, a worker may listen to the wrong queue, or an identity provider may redirect to another environment.
Check API origins, CORS rules, cookie domains, OAuth redirects, webhook callbacks, queues, topics, and consumer groups. Use test endpoints for email, payments, and other external side effects.
When the feature crosses an API, worker, database, or queue, troubleshooting only the public service leaves part of the request path hidden. Northflank Preview Blueprints can define multiple services, databases, jobs, and private connections in one preview. The microservices preview environment guide explains how to keep versions, routes, state, and asynchronous dependencies explicit.
Missing or stale configuration can look like an application bug. Compare variable names and sources without printing secret values.
Check whether the application needs each value during the build or at runtime. Then check whether the secret group is restricted to the relevant service, job, or tag. Look for a higher-priority group or resource-level variable overriding the expected value. Restart dependent workloads after changing inherited values.
When several preview resources need configuration, copying values into each service makes precedence and access harder to control. Northflank secret groups can provide build arguments, runtime variables, or both, with restrictions by resource or tag and priorities between groups. Values defined directly on a service or job override inherited values.
First separate connection failures from migration failures. Confirm that the database is ready, then check the hostname, port, database name, user, and TLS settings available to the job.
If it connects, inspect the job logs for an existing object, incompatible schema version, lock, timeout, unexpected data, or a partially completed earlier attempt. Make seed and migration jobs idempotent where practical, and avoid automatically retrying destructive migrations.
If application deployment depends on a schema change, the migration should be a visible step rather than an implicit startup action. Northflank can run migrations as workflow jobs before or after deployment and use their result to control later workflow steps. A deployment rollback does not by itself reverse a migration, so test recovery as well as the forward change.
Confirm that the provider delivered an event for the new commit and that it still matches the trigger rules. Then compare the pull request's head SHA, the build's commit SHA, and the image deployed to the service.
If the correct image is running, check browser, service-worker, and CDN caching before building again. A safe diagnostic endpoint that returns the commit SHA can make this easier.
A stable preview should follow the pull request without creating a separate environment for every revision. Northflank can update previews when new commits are pushed; its preview management guide recommends checking the Git trigger and provider webhook when updates do not appear.
Separate slow creation from slow application requests. Creation time may come from uncached builds, large images, serial provisioning, database restores, or unnecessary services. Runtime latency may come from CPU, memory, cold caches, or downstream dependencies.
Use timings and resource metrics before increasing every plan. Reuse stable builds, cache dependency layers, run independent steps in parallel, and include only the services required to test the change.
As the number of pull requests grows, per-preview sizing and fleet-wide limits both matter. Northflank's preview management guidance recommends smaller preview plans, automatic cleanup, maximum concurrent preview limits, and regular resource review.
A preview that remains after its pull request continues to consume resources and may leave an accessible URL or external test resource behind.
Check whether cleanup on pull-request close, merge, and inactivity is enabled. Confirm that the Git provider sent the relevant event. If the preview created resources in another provider, inspect their teardown separately.
Cleanup needs to follow the pull-request lifecycle rather than depend on someone remembering to delete each environment. Northflank can automatically delete previews on close, merge, or after an inactivity period. Resources created as part of the preview are removed with it, while externally created resources can be handled with a teardown specification.
Check the fix: close a test pull request and check both Northflank and external resources, including callbacks, buckets, test tenants, and snapshots.
Northflank Preview Environments bring the preview definition, builds, runtime resources, networking, configuration, and lifecycle controls into one platform. You can follow a failure from the pull request to the affected build, service, job, addon, or route.
For enterprise platform teams, this creates a consistent troubleshooting path across applications and engineering groups. Instead of asking every team to maintain separate preview scripts and piece together failures across several systems, platform teams can use reusable Preview Blueprints to define how environments are created, connected, observed, updated, and removed.
- Visibility across the complete preview run: The Preview Blueprint management view shows each preview's pull-request metadata, status, resources, and generated URLs, including whether it is building, running, or failed.
- Traceability from code to deployment: Build history connects each build to its branch and commit hash, alongside its duration, status, logs, and metrics. This helps teams confirm that the preview is running the code they intended to test.
- Build and runtime observability: Northflank provides live and historical logs for builds, deployments, jobs, addons, and terminated containers. Container metrics and status help separate application crashes from resource and health-check problems.
- Health-check visibility: Northflank supports HTTP, TCP, and command-based startup, readiness, and liveness checks, with results and timing available for individual containers. This makes it clearer why a running service is not receiving traffic or keeps restarting.
- Private and public network controls: Northflank networking covers private service communication, public ports, generated DNS, custom domains, path rules, and access policies. Teams can check the route to a service without rebuilding its application image.
- Scoped configuration and secrets: Secret groups keep build arguments and runtime variables outside the repository, with restrictions by resource or tag and priorities for resolving overlapping values.
- Migrations within the deployment workflow: Database migrations can run as workflow jobs, with later deployment steps continuing only after a successful migration when the workflow is configured that way.
- Automated updates and cleanup: Previews can update when new commits are pushed and be deleted on pull-request close, merge, or inactivity. Teardown steps can also remove resources created outside Northflank.
Run the workflow on Northflank Cloud, or deploy Northflank into your AWS, GCP, Azure, Oracle, CoreWeave, Civo, or Nebius account with BYOC.
Get started with Northflank self-serve, or book a demo to discuss standardising preview environments across teams, running them in your cloud account, or replacing an internally maintained preview platform.
The application may not be ready, may listen only on localhost, or may use a different port from the public route. Test the listener inside the container, then the private endpoint, and finally the public URL. On Northflank, you can check the container's health-check results and then verify its private and public port configuration.
Find the earliest stage that failed: the Git trigger, blueprint run, build, container, health check, or network route. Errors later in the process are often consequences of that first failure.
Your local environment may provide undeclared files, environment variables, credentials, cached dependencies, or services on localhost. Compare a clean container build and its runtime configuration with the preview environment to find what is missing or different. On Northflank, build history identifies the deployed commit, while container logs show how that build behaves at runtime.
