Diagnose deployment failures for Quarkus · Ample Computer

Diagnose deployment failures for Quarkus

Deployment diagnostics for a Quarkus app on Ample. Verified on Quarkus: the same app deployed with a deliberate boot failure (CANARY_FAIL=boot): ample deploy exited 1 with a coded failure (health_check_failed when the process dies at boot, public_ingress_failed when the framework boots but every request answers 500) and the app's own error line was readable with ample logs <deployment_id> --kind runtime, so the cause is read from the framework's output rather than guessed. Build and start: ./mvnw -q -DskipTests package producing one uber-jar (quarkus.package.jar.type=uber-jar), then java -jar on the jvm-21 template (Temurin JDK 21) with quarkus.http.port read from PORT.

Verified November 5, 2026

What it runs on

You need

Exact tested configuration

Steps

  1. Read the failure code. Deploy is synchronous. Exit 1 with build_failed means the isolated build failed; health_check_failed means the app built but never answered on PORT (it crashed at boot or bound the wrong port); public_ingress_failed means it answered on PORT but the public URL returned an error status (a request handler or bootstrap failed); exit 2 means a required preflight action is blocking.

  2. Read the build log. The last lines name the failing command and its output.

   $ ample logs <deployment_id> --kind build
  1. Read the runtime log. For health_check_failed the runtime log carries the Quarkus process output: in the verified run the deliberate boot failure's own error line was there, followed by the platform's health-check verdict and the start command it ran.
   $ ample logs <deployment_id> --kind runtime
  1. Fix and redeploy once. Change the source, the environment or the command override, then run ample deploy again. Do not loop deploys to poll status; an unchanged redeploy is a no-op.

  2. Verify. Fetch the live URL on the example; on failure read the build and runtime logs.

   $ ample logs <deployment_id> --kind build

How it was checked

✓ failed deploy reports health_check_failed synchronously · manual → “ample deploy exits 1 with error.code health_check_failed”
✓ runtime log carries the app's own error line · manual → “ample logs --kind runtime shows the framework's error output before the health-check verdict”

Evidence

  1. November 5, 2026 · canary run Quarkus pattern fixture deployed on Ample with CANARY_FAIL=boot (./mvnw -q -DskipTests package producing one uber-jar (quarkus.package.jar.type=uber-jar), then java -jar on the jvm-21 template (Temurin JDK 21) with quarkus.http.port read from PORT); the same app deployed with a deliberate boot failure (CANARY_FAIL=boot): ample deploy exited 1 with a coded failure (health_check_failed when the process dies at boot, public_ingress_failed when the framework boots but every request answers 500) and the app's own error line was readable with ample logs <deployment_id> --kind runtime, so the cause is read from the framework's output rather than guessed.

Tested examples

What it doesn’t cover