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 (iOS): Incorrect sdkKey, network issues, or invalid static config data passed to init(configData:)
• 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). (iOS) init is non-blocking — call try await sdk.ready() and handle ConvertError.invalidConfiguration for unrecoverable errors; transient network failures resolve degraded (not thrown).

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
• Cause (iOS): createContext() is called before ready() resolves and config is unavailable; decisioning will degrade gracefully (return nil/disabled) until config loads
• 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 (iOS): createContext() is synchronous and never throws — contexts can be created before ready() resolves. If visitorId is omitted, a persistent UUID is generated and stored in the Keychain automatically. Call try await sdk.ready() before invoking bucketing methods to ensure config is available.

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
• Solution (iOS): Check that the attributes passed to createContext(visitorId:attributes:) match the audience rules configured in Convert. runExperience(_:enableTracking:) returns nil when the visitor does not qualify — it never throws. See Rule Evaluation & Targeting for how rules are evaluated.

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 (iOS): Ensure ConvertConfiguration.networkTracking is not false. Check that enableTracking is not false on runExperience/runExperiences calls. Verify the SDK key. The event queue flushes automatically on a timer and on app foreground; events are persisted to disk on app background and recovered on next launch. If mid-session tracking was disabled via await sdk.setTrackingEnabled(false), re-enable it with await sdk.setTrackingEnabled(true) — suppressed events are not replayed. If handleEventsForBackgroundURLSession(identifier:completionHandler:) is not forwarded from your UIApplicationDelegate, background delivery still works (events are reconciled on next launch), but OS wake completion may be delayed.

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.