Prefect Deployment Launch Crash-on-Arrival Sentinel

A Prefect deployment with a missing work pool, a broken infrastructure block, or a bad deployment-level config fails within seconds of being launched - but if nothing is watching the launch itself, that failure sits silently in Prefect's own UI until someone happens to check. This blueprint launches a deployment without blocking on full completion, waits a short grace period, then reads Prefect's own flow run API directly to tell "it crashed immediately" apart from "it is genuinely still running", and alerts only on the former.

How it works

1. periodic_deployment_launch (io.kestra.plugin.core.trigger.Schedule) runs on whatever cadence the deployment itself needs, explicitly passing prefect_api_url, deployment_id, and crash_check_delay through its own inputs: block so the flow is self-contained when the trigger fires. Shipped disabled so a manual run can be verified first.
2. launch_flow_run (io.kestra.plugin.prefect.CreateFlowRun, wait: false) creates the flow run and returns immediately with flowRunId and flowRunUrl, deliberately not using the task's own built-in wait-and-throw behavior.
3. grace_period_before_crash_check (io.kestra.plugin.core.flow.Sleep, duration: crash_check_delay) gives Prefect's own infrastructure provisioning a fixed window to either start running or fail outright.
4. probe_flow_run_state (io.kestra.plugin.core.http.Request) reads /flow_runs/{id} directly - the same endpoint the plugin itself polls internally - returning the flow run's current state.type.
5. evaluate_launch_health (io.kestra.plugin.core.flow.If) branches on whether state.type is one of Prefect's own terminal failure states (FAILED, CRASHED, CANCELLED).
   • then (CRASHED_ON_LAUNCH): alert_launch_crashed reports the flow run ID, state, and Prefect UI URL to Slack.
   • else (LAUNCHED_OK): log_launch_healthy records that the run is progressing (SCHEDULED/PENDING/RUNNING) or already COMPLETED.
6. log_audit_complete always runs last, printing the flow run ID and state regardless of which branch fired.
7. The errors block alerts Slack separately if the flow itself fails outright - an unreachable Prefect API or an invalid deployment_id must not read as either launch state.

What you get

• A LAUNCHED_OK/CRASHED_ON_LAUNCH answer sourced directly from Prefect's own flow run API, not from the launching task's own opaque throw-on-failure behavior, which this blueprint deliberately bypasses to keep classification and alerting under this flow's control.
• Immediate infrastructure or deployment-config failures caught within one grace period, instead of discovered only when someone next opens the Prefect UI.
• A direct Slack link to the flow run in the Prefect UI alongside the alert, via flowRunUrl.
• A worked example of io.kestra.plugin.prefect.CreateFlowRun used with wait: false, paired with a generic io.kestra.plugin.core.http.Request against the same status endpoint the plugin polls internally - useful as a pattern for any Kestra flow that needs to launch a Prefect deployment without blocking on it.

Who it's for

• Platform teams using Kestra as the orchestrator-of-orchestrators that kicks off Prefect deployments as sub-steps and need to know immediately if one never got off the ground.
• Data engineering teams running self-hosted Prefect who want a crash-on-arrival signal without Prefect Cloud's own alerting.
• Anyone evaluating the Prefect plugin who wants a worked example of CreateFlowRun with wait: false, since every example in the plugin's own documentation uses wait: true.

Why orchestrate this with Kestra

CreateFlowRun with wait: true only ever gives you success or a thrown task failure - it cannot distinguish "launch and let it run" from "detect it crashed in the first 30 seconds and alert, but don't block this flow on the whole run." Kestra supplies the schedule, the grace-period probe as a first-class step, the LAUNCHED_OK/CRASHED_ON_LAUNCH branch, and an execution history that shows exactly when a launch failed and what Prefect's own API said about it.

Prerequisites

• A reachable self-hosted Prefect server with at least one deployment created (update prefect_api_url and deployment_id) - probe_flow_run_state's URL is not adapted for Prefect Cloud's account/workspace-scoped path; see Pitfalls.
• A Slack incoming webhook for alerts.

Local testing (self-hosted Prefect, no Prefect Cloud account needed):

docker run -d --name prefect-server -p 4201:4200 prefecthq/prefect:3-latest prefect server start --host 0.0.0.0
docker network connect YOUR_KESTRA_NETWORK prefect-server

Run docker network ls first to find the active Kestra network name. The container's internal port 4200 is mapped to host port 4201 here so it never collides with Kestra's own UI on port 8080; open http://localhost:4201 once to confirm the server is up, then use the Prefect CLI (prefect deploy) against this server to create a deployment and copy its deployment ID before pointing deployment_id at it. From inside the Kestra worker's Docker network, reach the server at http://prefect-server:4200/api instead of host.docker.internal.

Secrets

• PREFECT_API_KEY: sent as a Bearer token for Prefect Cloud or a Basic token for a secured self-hosted server, per io.kestra.plugin.prefect.CreateFlowRun's own documented behavior. Leave the secret set to an empty value for an unauthenticated local self-hosted server - the task only adds the Authorization header when a non-empty key is rendered.
• SLACK_WEBHOOK_URL: Slack incoming webhook used by alert_launch_crashed and the errors block.
• In Kestra OSS (no Enterprise secrets backend), secrets are supplied as environment variables prefixed SECRET_, base64-encoded - for example SECRET_SLACK_WEBHOOK_URL=$(echo -n '<your-webhook-url>' | base64) - and read back in flows with {{ secret('NAME') }}.

Inputs

• prefect_api_url (STRING, default http://host.docker.internal:4200/api): base Prefect API endpoint.
• deployment_id (STRING, default <your-prefect-deployment-id>, must be replaced): UUID of the deployment to launch.
• crash_check_delay (STRING, default PT30S, ISO-8601 duration): grace period before the crash probe.

Outputs

• outputs.launch_flow_run.flowRunId / flowRunUrl: identifiers for the created flow run, reused by the probe and surfaced in alerts.
• outputs.probe_flow_run_state.body: the raw /flow_runs/{id} JSON response; this blueprint only reads state.type, but every other field Prefect returns is present too.

Quick start

1. Start Prefect locally with the command above and create a deployment, copying its deployment ID.
2. Add the PREFECT_API_KEY (can be empty) and SLACK_WEBHOOK_URL secrets.
3. Run the flow manually with deployment_id set to your real deployment and confirm log_launch_healthy fires once the run reaches RUNNING or COMPLETED within the grace period.
4. Point deployment_id at a deliberately broken deployment (for example, one referencing a work pool that does not exist) and re-run to confirm alert_launch_crashed fires with the real Prefect state.
5. Enable periodic_deployment_launch once you trust the check against your real deployment and cadence.

How to extend

• Chain a second io.kestra.plugin.prefect.CreateFlowRun with wait: true after log_launch_healthy if the calling flow genuinely needs to block on full completion once the crash-on-arrival window has passed cleanly.
• Add a longer second Sleep plus another probe_flow_run_state call to also catch a deployment that crashes a few minutes in, past the initial infrastructure-provisioning window this blueprint is tuned for.
• Loop over several deployment_id values with io.kestra.plugin.core.flow.Loop to launch and crash-check an entire pipeline of deployments in one run.

Pitfalls

• io.kestra.plugin.prefect.CreateFlowRun has only one task in this plugin - there is no dedicated "get flow run" or "list flow runs" task. That is why probe_flow_run_state reads Prefect's REST API directly with a generic io.kestra.plugin.core.http.Request instead of a Prefect-specific Kestra task.
• crash_check_delay is a fixed grace period, not a wait-until-terminal-state poll. A flow run that is still RUNNING when the probe fires is reported LAUNCHED_OK even if it fails ten minutes later - this blueprint is tuned to catch launch-time failures, not full-run outcomes; see How to extend for chaining a blocking wait afterward.
• The /flow_runs/{id} endpoint and its nested state.type field are taken from io.kestra.plugin.prefect.CreateFlowRun's own source (the exact path and field it polls internally when wait: true), not from independently verified Prefect REST API reference documentation.
• This flow is scoped to self-hosted Prefect, not Prefect Cloud. probe_flow_run_state calls {{ prefect_api_url }}/flow_runs/{id} directly, which is correct when prefect_api_url is a self-hosted API root. Prefect Cloud instead routes flow runs under /accounts/{accountId}/workspaces/{workspaceId}/flow_runs/{id} (the same pattern io.kestra.plugin.prefect.CreateFlowRun's own PrefectConnection applies internally when accountId/workspaceId are set) - pointing prefect_api_url at Prefect Cloud without also rebuilding that path on probe_flow_run_state will probe the wrong URL.
• This blueprint is UNTESTED against a live Prefect server. The terminal state values (FAILED, CRASHED, CANCELLED, COMPLETED) are taken verbatim from the plugin's own isTerminalState logic, and the io.kestra.plugin.prefect.CreateFlowRun properties and outputs are taken from the plugin's own source on main - but no Docker container or Kestra engine was run to execute this flow end to end, and no deployment was deliberately broken to exercise the CRASHED_ON_LAUNCH path.

Links

• Kestra Prefect plugin documentation
• Prefect self-hosted server documentation
• Kestra secrets (OSS vs Enterprise)