troubleshooting

Troubleshooting

Common Errors

SDK Initialization Failed

• Cause (JS): Incorrect sdkKey or network issues
• Cause (PHP): Incorrect sdkKey, network issues, or no PSR-18 HTTP client installed
• Cause (Android): Incorrect sdkKey or network issues — on a failed config fetch the SDK loads the last cached config from app-private storage; with no cache, decision methods return null until the next successful fetch
• Solution: Verify the sdkKey and ensure network connectivity. If using an authenticated key, ensure sdkKeySecret is also provided. (PHP only) Install a PSR-18 HTTP client (e.g., composer require guzzlehttp/guzzle).

No PSR-18 HTTP Client Found (PHP only)

• Cause: php-http/discovery cannot find a PSR-18 HTTP client implementation
• Error message: No PSR-18 HTTP client found. Install one (e.g., guzzlehttp/guzzle ^7) or pass an explicit httpClient.
• Solution: Install one: composer require guzzlehttp/guzzle or any other PSR-18 compatible client.

User Context Creation Failed

• Cause (JS): Missing or invalid userId
• Cause (PHP): Missing or empty visitorId, or SDK not initialized
• Solution (JS): Ensure a valid, non-empty userId string is provided to createContext().
• Solution (PHP): Ensure a valid, non-empty visitorId string is provided to createContext(). Check that isReady() returns true before creating contexts.
• Solution (Android): createContext() with no arguments auto-generates and persists a UUID visitor id. Decision calls made before the SDK is ready return null (never throw) — gate them behind onReady { }.

Experience Not Found

• Cause: Incorrect experienceKey or experience not defined in the project
• Solution: Verify the experienceKey matches exactly. Ensure the experience is active (not draft or paused) and belongs to the correct environment.

Feature Not Found

• Cause: Incorrect featureKey or feature not linked to any experience
• Solution: Verify the featureKey. Ensure at least one active experience has a variation with a fullStackFeature change linked to this feature.

Visitor Not Bucketed (RuleError)

• Cause: The visitor's properties or location don't match the experience's audience/location rules
• Solution (JS): Check that the visitorProperties and locationProperties passed to the method match the rules configured in Convert. See Rule Evaluation & Targeting for how rules are evaluated.
• Solution (PHP): Check that the visitorProperties and locationProperties in BucketingAttributes match the rules configured in Convert. The RuleError enum has two cases:
  • RuleError::NoDataFound -- no matching data for the rule
  • RuleError::NeedMoreData -- insufficient data provided to evaluate the rule

Tracking Events Not Appearing

• Cause: Tracking is disabled, events are still queued, or the SDK key is invalid
• Solution (JS): Ensure network.tracking is not false in the config. Call releaseQueues() to flush pending events. Verify the SDK key. Check that enableTracking is not false in method attributes.
• Solution (PHP): Ensure network.tracking is not false in the config. Call releaseQueues() or flush() to send pending events. Verify the SDK key. The shutdown handler should flush automatically in PHP-FPM, but in CLI scripts you may need to call flush() explicitly.
• Solution (Android): Check that tracking wasn't disabled via trackingEnabled(false) at build time, setTrackingEnabled(false) at runtime, or enableTracking = false on the call. Offline events are queued durably and ship when connectivity returns — declare ACCESS_NETWORK_STATE so the SDK can flush immediately on reconnect.

Config Validation Failed (PHP only)

• Cause: The fetched or provided project configuration is malformed
• Solution: If using static data, verify the structure matches the Convert Serving API format. If using sdkKey, the CDN response may be temporarily invalid -- the SDK will throw a ConfigValidationException.