> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hightouch.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshoot events

> Start here when something looks wrong with your event data. Each section starts from a symptom, points to the likely cause, and links to the fix.

Start with these two tools:

* The [debugger](https://docs.hightouch.com/events/sources/overview.md#debugger) shows individual events as they arrive, so you can confirm exactly what Hightouch received.
* The `event_violations` table in your warehouse records every event that failed contract validation, along with the reason. See [handling violations](https://docs.hightouch.com/events/contracts/violations.md).

## Events aren't arriving, or volume is lower than expected

Work through these in order:

* **Confirm receipt in the debugger.** If events don't appear there, the problem is upstream of Hightouch — the SDK isn't firing, or the write key or region is wrong. Check that you're using the write key from your event source.
* **Expect some client-side loss.** Browser events are dropped by ad blockers, privacy settings such as Safari ITP, and cookie limits. This is inherent to client-side collection, not a setup error. Reduce it with [first-party tracking](https://docs.hightouch.com/events/first-party-tracking.md), and move business-critical events to [server-side collection](https://docs.hightouch.com/events/sdks/http.md). See [Plan for coverage](https://docs.hightouch.com/events/implementation-plan.md#plan-for-coverage).
* **Check whether a contract is blocking events.** If enforcement is set to block, undeclared or invalid events are dropped from your main tables. See the next section.

## An event is blocked or flagged

A contract [violation](https://docs.hightouch.com/events/contracts/violations.md) means an event didn't satisfy the contract applied to its source. The match is exact, so the usual causes are small mismatches:

* The event name doesn't match the contract, including capitalization and whitespace.
* A field is in the wrong section — for example, sent under `properties` when the contract expects it under `context`.
* A field's type doesn't match the schema.
* The contract is empty while set to block undeclared events, so everything is blocked.

Work through these with [Diagnose why an event was blocked or flagged](https://docs.hightouch.com/events/contracts/violations.md#diagnose-why-an-event-was-blocked-or-flagged), which maps each cause to its fix.

## Unexpected or extra columns in the warehouse

Your warehouse tables mirror the data you send — Hightouch structures it but doesn't clean it. Extra or odd columns usually trace back to the input:

* A misspelled or inconsistently named property creates a new column whenever it varies.
* Malformed URL or campaign parameters — for example, a missing `=` in a UTM tag — land as unexpected fields.
* Nested objects are flattened into separate columns (`company.name` becomes `company_name`).

Validate the inbound data before changing anything in the warehouse. See [Warehouse schema](https://docs.hightouch.com/events/warehouses/schema.md) for how columns and types are created.

## An event was rejected and not written

If an event's value doesn't match the existing column type — for example, a string where the column is a number — Hightouch can't write it. It [retries the event for 48 hours](https://docs.hightouch.com/events/warehouses/error-handling.md), so correcting the type in your warehouse lets the event sync without data loss. See [Error handling](https://docs.hightouch.com/events/warehouses/error-handling.md).

## Data doesn't match my previous tool

During a migration, some difference between systems is normal — timing, deduplication, ad blockers, and Hightouch's stricter blocking all cause minor variation. Before treating a gap as a bug, see [what differences to expect](https://docs.hightouch.com/events/migration-guide/validating-your-migration.md#what-differences-to-expect-between-your-old-provider-and-hightouch-events) and the parity checks in [Validate your migration](https://docs.hightouch.com/events/migration-guide/validating-your-migration.md).

## Still stuck?

Set up [monitoring and alerts](https://docs.hightouch.com/events/monitoring.md) so you catch issues early, and [contact support](#pylon-chat) if you can't resolve a problem.