SDK Troubleshooting and Debugging

Data validation is a critical step in the instrumentation process. Amplitude provides tools that streamline debugging and support smooth implementation of your projects.

The following sections cover common issues and their solutions.

Events not showing in Amplitude

If you can't ingest any event, check the following:

• Are you using the correct API key? Check that you set the API key correctly during init(). If you enabled data residency in the EU, retrieve your API key from https://analytics.eu.amplitude.com/. Data locality regulations store your API details there.

• Are you using multiple instances? Confirm you're using the correct instance. Multiple SDK versions can conflict. To avoid conflicts, give each instance a different name. For the latest SDKs, you may need to create separate variables to instantiate them differently.

• Are you using Amplitude Data? If you're using Amplitude Data, check that the event isn't blocked.

• Are you setting valid userId and deviceId values? Check that your deviceId or userId is valid. An invalid value can cause a 400 error. For details, refer to device IDs and user IDs minimum length.

• Did you hit the flushQueueSize or flushIntervalMillis? By default, the SDK queues events and sends them in batches, so events don't reach the server immediately. The exact values differ by platform. Wait for events to reach the server before checking for them in charts.

Endpoint limits and throttling

Amplitude enforces endpoint limits to protect the platform from traffic spikes. Understanding these limits helps you handle rate limiting scenarios effectively.

Endpoint limits

Amplitude sets limits on the number of events each endpoint can process per second:

• Default limit: 100,000 events per project per second (counted separately for each endpoint).
• Group identify endpoint: 10,000 events per organization per second.
• SDK endpoint: 150,000 events per project per second.
• HTTP API and HTTP API v2: 50,000 events per project per second.

When you exceed these limits, Amplitude returns an HTTP 429 status code. Wait 60 seconds before resending events.

Normal throttling

Amplitude also enforces a throttling limit of 30 events per user or device per second across your entire organization. This limit applies to all endpoints, including the SDK endpoint, and protects against excessive event volume from individual users or devices.

If you exceed this limit, Amplitude throttles the events and logs a warning. Distribute your event tracking across time or reduce the frequency of event calls to stay within this limit.

Privacy

If you've already disabled IP, you may still see the IP in your user lookup when using the latest SDK. Amplitude sends data to the HTTP API (HTTP API V1 for the maintenance SDK and HTTP API V2 for the latest SDK). If you disabled the IP address partway through, Amplitude may have saved the user's previous IP address in the backend. The backend retrieves the saved IP from the database, if one exists. For a test user, this is usually fine. It doesn't affect new users after you disable the IP. If this affects all users, create a new workspace.

Client Event Time shows unexpected value

Client Event Time is the local timestamp (UTC) when the device logged the event. For explanations of the different Amplitude timestamps, refer to Raw data fields.

• Client Event Time shows a future time Check this section if client_upload_time shows a time in the future. The customer's device determines client_upload_time. The value can appear as a future time if the customer's clock is set incorrectly. If you use the latest SDK, you can remove the time from the event payload through the Enrichment Plugin. The Enrichment Plugin stops the SDK from using the customer's device clock and relies on server_upload_time instead. This approach has a downside: if events don't upload immediately, the recorded event time can differ significantly from the original event time.

• Client Event Time differs from Client Upload Time Client Event Time may differ from Client Upload Time. To support high-performance environments, the SDK sends events in batches. The SDK queues every event logged by the track method on the client side. The SDK batches and flushes events when either flushQueueSize or flushIntervalMillis meets the defined value first. As a result, the SDK can track an event and upload it later. Adjust flushQueueSize and flushIntervalMillis or call flush() manually to send events more frequently.

Device family isn't appropriate

• For web, Amplitude uses a third-party library to parse the Navigator.userAgent info, except @amplitude/analytics-browser@^2.0. If you find an inappropriate device family, first confirm that the value of Navigator.userAgent matches expectations. Starting in Chrome 110, Chrome uses a fixed value for Android version and device model. Chrome's user-agent reduction may affect device info.

• For mobile SDKs, Amplitude relies on server device mapping. Amplitude references Google's supported devices list and List of Android smartphones for Android, and Comparison of tablet computers for iOS. If you find an inappropriate device family that doesn't appear in any of these sources, submit a ticket.

user_properties through identify call showing up late

A race condition can occur if the request doesn't include a deviceId or doesn't go through the batch API. The Amplitude backend uses partition logic. Without the same deviceId, or without using the batch API, two calls can fall into separate buckets. Amplitude can't guarantee processing time across different buckets and queues. To maintain the order of identify calls and track calls, send the calls with the same deviceId through the batch API.

To reduce the number of requests, the latest mobile SDKs queue and consolidate certain Identify updates. The SDKs wait to send them along with the next non-Identify event sent through track(). To update user properties immediately, call flush().

Event times are very inaccurate

If sessions from certain users report inaccurate event times (for example, hundreds of years in the future or past), the most likely causes are:

• The end user has an anomalous configuration that sets the device to an incorrect date.
• The end user has a browser extension that causes inaccurate time reporting.

These issues don't indicate an error in your instrumentation.