For AI agents: a Markdown version of this page is at https://docs.snowplow.io/docs/failed-events.md. The index of all documentation pages is at https://docs.snowplow.io/llms.txt, and the index for this section is at https://docs.snowplow.io/docs/cdi/llms.txt.
Failed events hub
Failed events are events the pipeline couldn't process, for example because they didn't match their schema or an enrichment failed. The pipeline keeps them separate, so they don't affect the data in your warehouse, and you can fix and reprocess many of them. The failed events fundamentals page explains why events fail and where they go.
The pages about failed events live in four parts of the docs: Fundamentals, Get started, Monitor and operate, and Reference. This page lists them by task.
| I want to | Go to |
|---|---|
| Understand what a failed event is | Introduction to failed events |
| See failed events for the first time | Inspecting your first failed events |
| Find out why a specific event failed | Failed event types |
| See failed event volumes in Console | Monitor failed events |
| Get notified when events start failing | Set up failed event alerts |
| Query failed events with SQL | Load failed events into warehouse or lake |
| Reprocess failed events | Recover failed events |
| Catch failures before they reach production | Test your tracking and pipeline |
Understand failed events
Each failed event has a type that says which pipeline stage rejected it, such as a schema violation, an enrichment failure, or a loader error. The type tells you where to look for the cause and whether you can recover the event.
- Introduction to failed events: what failed events are, and where the pipeline sends them
- Failed event types: every failed event type, its cause, and whether it can be recovered
- Inspecting your first failed events: send an invalid event to a new pipeline and find it
Monitor and alert
Console shows failed events in two views. The data quality dashboard reads complete failed events from your warehouse, through an API that runs in your infrastructure. The default view shows redacted aggregates and needs no extra setup. Monitor failed events compares them.
- Monitor failed events: the data quality dashboard, the default view, and the Console API
- Set up failed event alerts: choose between warehouse-based and classic alerts
- Failed event alerts, create alerts, and manage alerts
- Classic alerts: new failed event notifications and daily digests from telemetry data
Load and query
To see complete failed events, and to recover them with SQL, load them into your warehouse or lake with a Failed Events Loader. Without a loader, the raw failed events are still in your cloud storage.
- Load failed events into warehouse or lake: configure the Failed Events Loader, and query the failed events table
- Access raw failed events from S3 or GCS buckets: query the files directly with Athena or BigQuery
Recover failed events
How you recover failed events depends on where they are. If you load them into a table, recover them with SQL. If they're only in S3 or GCS, run a manual recovery job.
- Recover failed events: choose a recovery method
- Recover loaded events from a failed events table with SQL: the recommended method
Recover failed events manually from buckets
Manual recovery runs a job that reads failed events from your buckets, applies the fixes you configure, such as replacing or removing values or casting types, and replays the fixed events through your pipeline. Work through the pages in this order:
- Event recovery without Failed Events Loader: when to use manual recovery
- Introduction to manual failed event recovery: how a recovery job works
- Configure an event recovery job, with configuration examples
- Test an event recovery configuration locally
- Run event recovery jobs on Flink, GCP Dataflow with Beam, or Spark (legacy)
- Monitor event recovery jobs
- Troubleshoot the manual event recovery process
For common recovery scenarios, see manual event recovery workflows. To write your own recovery steps, see extend and customize an event recovery job.