RudderStack Python SDK

Common errors

• SDK returns success, but events are not visible in the destination.

  cause Several potential causes: RudderStack server is in 'degraded' or 'maintenance' mode, incorrect data plane URL or write key, Control Plane is inaccessible, or the specific destination is not enabled or misconfigured in the RudderStack dashboard.
  fix 1. Verify your `rudder_analytics.write_key` and `rudder_analytics.dataPlaneUrl` are correct. 2. Check the status of your RudderStack server/data plane (if self-hosted) or the RudderStack cloud dashboard. 3. Confirm the destination is enabled and configured correctly in your RudderStack workspace. 4. Enable `rudder_analytics.debug = True` for more verbose logging.

• HTTPSConnectionPool(...): Max retries exceeded with url: ... (Caused by ProxyError or ConnectionError)

  cause Network connectivity issues preventing the SDK from reaching the RudderStack data plane, potentially due to firewall rules, proxy misconfiguration, or an unavailable data plane server. While this specific error often appears with `rudder-cli`, similar underlying network problems can affect the SDK.
  fix 1. Check your network connection and proxy settings. 2. Ensure the `DATA_PLANE_URL` is accessible from your application's environment. 3. Verify that any firewalls are configured to allow outbound HTTP/HTTPS connections to your data plane URL. 4. Increase the `timeout` configuration option for the SDK if transient network issues are expected.

• Events are being sent successfully but appear in the destination with significant delay.

  cause This usually indicates a bottleneck in processing, either on the RudderStack backend side or the destination service itself. Possible reasons include a high rate of incoming events overwhelming the system or a temporary outage/degradation of the destination service.
  fix 1. Check the status of your destination service (e.g., Google Analytics, S3). 2. If self-hosting RudderStack, monitor your server resources and consider scaling up if the incoming event rate consistently exceeds processing capacity. 3. Review RudderStack dashboard metrics for any alerts on pending events or degraded performance.

Warnings

• gotcha The Python SDK does not persist user state. You must explicitly provide either `user_id` or `anonymous_id` with every event API call (e.g., `track`, `identify`, `page`). Failing to do so will result in events not being processed correctly or being dropped.
  Fix: Always pass `user_id` or `anonymous_id` as an argument to event methods: `rudder_analytics.track('user_id_123', 'Event Name')`.
• gotcha The SDK blocks the calling thread until all messages are flushed from the queue. Avoid using SDK calls directly within the critical path of a request lifecycle (e.g., in web server request handlers) to prevent performance bottlenecks.
  Fix: Consider using asynchronous processing (e.g., a background thread, a message queue, or a dedicated worker) for RudderStack event calls in performance-sensitive applications.
• gotcha The Python SDK drops any event data larger than 32KB without logging a warning. Ensure your event payloads (including properties and context) do not exceed this size limit.
  Fix: Monitor event sizes and truncate or restructure large event payloads to stay within the 32KB limit. Split large events into multiple smaller events if necessary.

Install

• pip install rudder-sdk-python Install latest version

Imports

• rudderstack.analytics
  wrong:

  import rudderstack.analytics

  correct:

  import rudderstack.analytics as rudder_analytics

  Aliasing as 'rudder_analytics' (or 'analytics') is a common convention in examples and helps distinguish it from other modules.

Quickstart

Initialize the RudderStack Python SDK with your source write key and data plane URL, then use `identify`, `track`, and `page` methods to send customer events. Remember to call `flush()` to ensure all buffered events are sent before your application exits.

import os
import rudderstack.analytics as rudder_analytics

# Set your RudderStack Write Key and Data Plane URL from environment variables
# Replace with your actual values or use environment variables for production
WRITE_KEY = os.environ.get('RUDDERSTACK_WRITE_KEY', 'YOUR_WRITE_KEY')
DATA_PLANE_URL = os.environ.get('RUDDERSTACK_DATA_PLANE_URL', 'YOUR_DATA_PLANE_URL')

rudder_analytics.write_key = WRITE_KEY
rudder_analytics.dataPlaneUrl = DATA_PLANE_URL

# Optional: Configure debug mode for verbose logging
rudder_analytics.debug = True

# Identify a user
rudder_analytics.identify(
    user_id='user_123',
    traits={'name': 'John Doe', 'email': 'john.doe@example.com'}
)

# Track an event
rudder_analytics.track(
    user_id='user_123',
    event='Product Viewed',
    properties={'product_id': '456', 'product_name': 'Example Widget'}
)

# You can also use anonymous_id if user_id is not available
rudder_analytics.page(
    anonymous_id='anon_789',
    name='Homepage',
    category='Marketing'
)

# Ensure all queued events are sent before exiting
rudder_analytics.flush()

print('Events sent to RudderStack.')