Roku SDK Error Reference

The StreamLayer Roku SDK does not use numeric error codes. Instead, it surfaces problems as structured log messages through its logging interface. This page maps each message to its cause and fix.

For setup steps, see the Integration Guide. For the methods referenced below, see the API Reference.

Enable logging first

Error and warning messages are only emitted when logging is enabled. Pass
isLoggingEnabled: true to initSdk, then read the SDK's log field (or your
Roku debug console) to see them.
m.streamLayer.callFunc("initSdk", { apiKey: "your-sdk-api-key", isLoggingEnabled: true })

Severity levels

Level	Meaning
`error`	A required step failed; the SDK could not complete the operation.
`warn`	The SDK recovered or skipped an optional step; integration may be misconfigured.

Initialization

Message	Level	Cause	Fix
`❌ initSdk: params missing`	error	`initSdk` was called with no params object. `initSdk` returns `false`.	Pass a params object with at least `apiKey`. See API Reference → initSdk.
`initSdk: Missing API key`	error	`params.apiKey` is empty or `invalid`.	Provide a valid SDK API Key from StreamLayer Studio.
`SDK initialization failed`	error	The underlying SceneGraph SDK runtime failed to initialize after config load.	Verify network access and that the API URL/key are correct; check earlier log lines for the root cause.
`[SDKFactory] Failed to initialize ApiService`	error	The network/API service could not be created.	Confirm the device has network access and `apiUrl` is reachable.
`[SDKFactory] Failed to initialize AnalyticsService`	error	The analytics service could not be created while `isAnalyticsEnabled` is `true`.	Check network access; disable analytics (`isAnalyticsEnabled: false`) to isolate the issue.

Player attachment

Message	Level	Cause	Fix
`Provided playerRef is not an roSGNode (type = ...)`	warn	The `playerRef` passed to `initSdk` / `attachPlayer` is not a SceneGraph node.	Pass the host `Video` node, not a plain object or `invalid`.
`Provided playerRef is not Video-like (subtype = ...)`	warn	The node is an `roSGNode` but lacks the `control` and `state` fields.	Pass an actual `Video` node (or a node that exposes `control` and `state`).
`setEvent: Player not attached`	error	`setEvent` was called before a valid player was attached.	Call `attachPlayer` (or pass `playerRef` to `initSdk`) before `setEvent`.

Event & subscriptions

Message	Level	Cause	Fix
`[SDKFactory] AuthManager or EventManager not initialized — cannot set event`	error	`setEvent` ran before authentication/SDK setup completed.	Wait for successful initialization before calling `setEvent`; ensure `initSdk` returned `true`.
`[SDKFactory] Gamification disabled — skipping event setup`	warn	The organization has gamification disabled in StreamLayer Studio.	Expected when gamification is off. Enable it in Studio if interactive units are needed.
`[SDKFactory] Cannot fetch question subscriptions – invalid organizationId`	error	Organization data was missing when polling started.	Ensure authentication succeeded (see Authentication errors below).
`[SDKFactory] Cannot fetch question subscriptions – invalid eventId`	error	`setEvent` was called with an empty event id.	Pass a non-empty `hostEventId` to `setEvent`.

Pause ad units

Message	Level	Cause	Fix
`showPauseAd ignored: currentEventId invalid`	error	`showPauseAd` was called before an event was set.	Call `setEvent` first so the SDK knows which event to load pause ad units for.
`showPauseAd ignored: vastUrl missing`	error	In VAST mode, `showPauseAd` was called without a `vastUrl`.	Pass `{ vastUrl: "..." }` to `showPauseAd`, or switch off VAST mode.
`[SDKFactory] PauseAdManager not initialized`	warn	A pause ad action ran before the pause ad subsystem was ready.	Ensure `isPauseAdsEnabled` is `true` and initialization completed.
`[SDKFactory] Invalid eventId for pause ads`	warn	A pause ad was requested with no active event.	Call `setEvent` before requesting pause ad units.
`[SDKFactory] VASTManager not initialized`	error	A VAST operation ran while VAST mode was not properly initialized.	Enable VAST mode via `initSdk` (`isVastModeEnabled: true`) or `setVastModeEnabled` before showing VAST pause ad units.

Authentication

These come from AuthManager during the anonymous login / token exchange that runs after initSdk.

Message	Level	Cause	Fix
`[AuthManager] Invalid organization response`	error	The organization settings request returned an unparseable response.	Verify the SDK API Key and API URL; confirm the key is active in StreamLayer Studio.
`[AuthManager] Cannot start anonymous login — org data missing`	error	Login started before organization data was available.	Usually follows an invalid organization response — fix that first.
`[AuthManager] Failed to parse BypassAuthResponse`	error	The authentication endpoint returned an unexpected payload.	Check API connectivity and that the key is valid; retry.
`[AuthManager] Cannot get JWE — missing data`	error	Required data for the JWE exchange was absent.	Ensure authentication completed; check earlier auth log lines.
`[AuthManager] JWE token invalid`	error	The JWE token returned by the server failed validation.	Verify the SDK API Key and that server clocks/credentials are valid; retry.
`[AuthManager] JWT token invalid`	error	The exchanged JWT failed validation.	Same as above — confirm credentials and retry; contact support if it persists.
`[AuthManager] Failed to parse UserSettingsResponse`	error	The user settings response was unparseable.	Check API connectivity; report to support with logs if it recurs.

"Method not available" warnings

Message	Level	Cause	Fix
`safeSdkCall: SDK not initialized (method=...)`	error	A method was invoked before `initSdk` completed.	Call `initSdk` and wait for success before other calls.
`safeSdkCall: method '...' not available in current SDK mode`	warn	A method was called that does not exist in the active mode (for example, a VAST-only call in full mode).	Use the method that matches your mode, or switch modes with `setVastModeEnabled`. This is a safe no-op.

Still stuck?

If an error persists after applying the fix, capture the SDK log (isLoggingEnabled: true) and contact [email protected]. Include the SDK version from getVersion() and the surrounding log lines.