# How to debug invalid analytic events **URL:** https://heroiclabs.com/docs/satori/guides/debug-invalid-events/ **Summary:** Use the Taxonomy Debugger in the Satori console to identify, inspect, and fix events rejected at ingestion. **Keywords:** debug events, satori debugger, invalid events, taxonomy, event validation, event schema **Categories:** satori, liveops, guides --- # How to debug invalid analytic events Satori validates every incoming analyic event against the event definitions you've configured: the expected name, value format, and metadata structure. Events that fail validation are captured in a temporary buffer. This guide walks you through how to use the Taxonommy Debugger to identify the rejection reason and apply the fix. ## Before you begin Ensure you have: - Access to the Satori console for your project - Events being sent from a client or server (so rejections are present in the Debugger) ## Open the Debugger In the Satori console, navigate to **Taxonomy**. Select the **Debugger** tab. The Debugger lists all rejected analytic events and the time they were received. ## Identify the rejection reason Select a row to view the full event payload in the details panel on the right. The payload includes a `_eventError` field in `metadata` with a plain-language description of what Satori detected. {{< screenshot src="images/pages/satori/guides/debugger-events/debugger_guide_debugger_list.png" alt="The Taxonomy Debugger tab showing a list of rejected events with event name, rejection reason, and receive time" >}} ## Fix the invalid events Use the rejection reason from the Debugger to find the relevant section below. - [INVALID_NAME](#invalid_name) - [INVALID_VALUE](#invalid_value) - [INVALID_METADATA](#invalid_metadata) - [VALUE_LENGTH_EXCEEDED](#value_length_exceeded) - [METADATA_SIZE_EXCEEDED](#metadata_size_exceeded) - [INVALID_ID](#invalid_id) ### INVALID_NAME Satori received an event name that doesn't match any event declared in your taxonomy. This is the most common reason for rejection during initial integration, or when a client sends an event that hasn't been added to the taxonomy yet. Take a `giftSent` event appearing in the Debugger. Selecting it, you can see it's flagged with `_eventError: "Event name invalid"`. {{< screenshot src="images/pages/satori/guides/debugger-events/debugger_giftsent_invalid.png" alt="The giftSent event rejected with INVALID_NAME, showing the event payload with _eventError: Event name invalid" >}} Searching for `giftSent` in the **Events** tab returns no results, confirming the event name isn't declared in the taxonomy. {{< screenshot src="images/pages/satori/guides/debugger-events/debugger_giftsent_not_in_taxonomy.png" alt="The Taxonomy Events tab with giftSent entered in the search field, showing No data was found" >}} #### How to fix For `giftSent`, create the event in your taxonomy under **Taxonomy > Events**. Once declared, the original payload will be accepted. {{< screenshot src="images/pages/satori/guides/debugger-events/debugger_giftsent_definition_taxonomy.png" alt="The Create Event dialog in Taxonomy with giftSent entered as the event name, Value set to String, and Metadata set to Object" width="70%" >}} If the event name was a client-side typo, update your client to match an event already declared in your taxonomy. Every event name your client sends must be declared in Satori before it will be accepted. ### INVALID_VALUE The `value` field sent by the client doesn't match the type defined in the event's schema validator. Take this `progressionUpdated` event, which is a Satori core event. The detail panel shows `_eventError: "Event value invalid"`, and the `value` field in the payload is a string. {{< screenshot src="images/pages/satori/guides/debugger-events/debugger_progressionUpdated_invalid.png" alt="The progressionUpdated event rejected with INVALID_VALUE, showing value: spikor and _eventError: Event value invalid" >}} In the Taxonomy/Events tab, the `progressionUpdated` schema declares `value` as **Number**, so any non-numeric value is rejected. {{< screenshot src="images/pages/satori/guides/debugger-events/debugger_guide_progressionUpdated_schema.png" alt="The progressionUpdated event schema showing Value set to Number and Metadata set to Object" width="70%" >}} #### How to fix For `progressionUpdated`, the `value` field must be a numeric value to match the **Number** schema. For example: ```json { "value": "42", "metadata": { "eventType": "events", "world": "unknown" } } ``` In general, check the event's schema under **Taxonomy > Events** and ensure the `value` field matches the declared type. If the schema definition itself is wrong, update the validator in your taxonomy. ### INVALID_METADATA The `metadata` object doesn't conform to the schema validator assigned to the event. Say you spot an `adImpression` event in the Debugger flagged with `_eventError: "Event metadata invalid"`. The `metadata` field contains `"currency": "USDX"`. {{< screenshot src="images/pages/satori/guides/debugger-events/debugger_adimpression_invalid.png" alt="The adImpression event rejected with INVALID_METADATA, showing currency: USDX and _eventError: Event metadata invalid" >}} In the Taxonomy/Events tab, `adImpression` is a Satori core event, meaning you cannot modify its schema. It uses a custom schema validator named `Event-Revenue-Metadata`. To see exactly what the validator requires, navigate to **Taxonomy > Schema Validators** and find `Event-Revenue-Metadata`. {{< screenshot src="images/pages/satori/guides/debugger-events/debugger_guide_adimpression_schema.png" alt="The adImpression event schema showing Metadata set to the Event-Revenue-Metadata schema validator" width="70%" >}} The schema validator defines `currency` as a string with exactly 3 characters (`minLength: 3, maxLength: 3`). `USDX` is 4 characters and fails that constraint. {{< screenshot src="images/pages/satori/guides/debugger-events/debugger_evetrevenue_schemaValidator.png" alt="The Event-Revenue-Metadata schema validator showing currency defined as a string with minLength and maxLength of 3" >}} #### How to fix For `adImpression`, `"USDX"` is 4 characters. Replace it with a valid 3-character currency code. For example: ```json { "value": "banner_top", "metadata": { "currency": "USD", "amount": "0.05" } } ``` In general, check the event's schema validator under **Taxonomy > Schema Validators** and ensure your metadata satisfies its constraints. If the validator definition itself is wrong, update or replace it in your taxonomy. ### VALUE_LENGTH_EXCEEDED The `value` field exceeds the maximum allowed length of 4,096 characters. This limit applies to all value types, though in practice it is most relevant for String values. If you see a `tutorialStep` event flagged with `_eventError: "Event value exceeds the maximum length allowed"`, select it in the Debugger to inspect the payload. The `value` field contains a string that exceeds the 4,096 character limit. {{< screenshot src="images/pages/satori/guides/debugger-events/debugger_tutorialstep_invalid.png" alt="The tutorialStep event rejected with VALUE_LENGTH_EXCEEDED, showing a truncated long value string and _eventError: Event value exceeds the maximum length allowed" >}} Searching for `tutorialStep` in **Taxonomy > Events**, the schema declares `value` as **String**. {{< screenshot src="images/pages/satori/guides/debugger-events/debugger_guide_tutorialStep_schema.png" alt="The tutorialStep event schema showing Value set to String and Metadata set to ANY" width="70%" >}} #### How to fix For `tutorialStep`, replace the long string with a concise identifier and move any descriptive content into `metadata`. For example: ```json { "value": "step_3", "metadata": { "description": "Equip your first weapon" } } ``` In general, keep `value` short and use `metadata` for longer or structured data. ### METADATA_SIZE_EXCEEDED The total byte size of the `metadata` object exceeds the maximum allowed. For example, in the Debugger tab an `inventoryUpdated` event is flagged with `_eventError: "Event metadata exceeds the maximum bytes allowed"`. The `metadata` field contains a large number of `inventorySlot_N` keys, each with a long item identifier string. The rejection is driven by the payload size limit, which is 4096 bytes by default. {{< screenshot src="images/pages/satori/guides/debugger-events/debugger_inventoryupdated_invalid.png" alt="The inventoryUpdated event rejected with METADATA_SIZE_EXCEEDED, showing many inventorySlot keys with truncated long values" >}} #### How to fix Reduce the amount of data in your `metadata` object so it's under the default 4096 bytes limit. If your game legitimately requires larger metadata payloads, you can raise the limit by setting the `event_payload_metadata_bytes_max` configuration option in your Satori deployment under **HeroicCloud > [your deployment] > Deployment > Edit Deployment**. ### INVALID_ID The `id` field on an event is optional. If you don't set it, Satori automatically generates a UUID v4. If you do set it (for example, to deduplicate retried events), it must be a valid UUID v4. Any other format is rejected. Say you open the Debugger and find an `achievementUnlocked` event flagged with `_eventError: "Event identifier invalid"`. The `id` was sent as `"session#2026/04/30@player!001"`. {{< screenshot src="images/pages/satori/guides/debugger-events/debugger_achievementunlocked_invalid.png" alt="The achievementUnlocked event rejected with INVALID_ID, showing an id with special characters and _eventError: Event identifier invalid" >}} Event definition: {{< screenshot src="images/pages/satori/guides/debugger-events/debugger_guide_achivementunlocked_schema.png" alt="The achievementUnlocked event schema showing Value set to String and Metadata set to ANY" width="70%" >}} #### How to fix If you don't need deduplication, remove the `id` field entirely and let Satori generate one. Only set `id` when you need retry deduplication. When set, it must be a valid UUID v4. ## Verify the fix After updating your client or taxonomy: 1. Re-send the affected event. 2. Return to **Taxonomy > Debugger** and confirm the event no longer appears in the debugger. ## Related - [Understand events](../../concepts/performance-monitoring/understand-events/) - [Send server-side events](../server-events/)