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 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.

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, and move business-critical events to server-side collection. See 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 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, 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 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, so correcting the type in your warehouse lets the event sync without data loss. See Error handling.

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 and the parity checks in Validate your migration.

Still stuck?

Set up monitoring and alerts so you catch issues early, and if you can't resolve a problem.