Errors and Troubleshooting

OpenSteer has three error layers you will actually run into: protocol errors, high-level SDK or CLI runtime errors, and cloud control-plane errors.

Protocol errors

The published protocol codes are:

invalid-request
invalid-argument
invalid-ref
unsupported-version
unsupported-operation
unsupported-capability
not-found
stale-node-ref
session-closed
page-closed
frame-detached
timeout
navigation-failed
permission-denied
conflict
profile-unavailable
auth-failure
auth-recovery-failed
browser-required
rate-limited
operation-failed
internal

SDK and transport layers can surface these as OpensteerProtocolError.

High-level runtime errors

These messages cover the main migration and setup failures:

Specify exactly one of element, selector, or persist.
waitForPage timed out
route() is not available for this session runtime.
interceptScript() is not available for this session runtime.
browser.* helpers are only available in local mode.
browser.clone() requires a persistent workspace browser.
browser.reset() requires a persistent workspace browser.
browser.delete() requires a persistent workspace browser.
provider=cloud requires OPENSTEER_API_KEY or provider.apiKey.
provider=cloud requires OPENSTEER_BASE_URL or provider.baseUrl.
record with provider=cloud requires OPENSTEER_CLOUD_APP_BASE_URL or "--cloud-app-base-url".
Cloud mode does not support browser.mode="attach".
record does not support browser.mode="attach".
record requires engine=playwright.
record requires a headed browser. Remove "--headless true".
ABP is not supported for provider=cloud. Cloud provider currently requires Playwright.
Saved-network operations require Node's built-in SQLite support. Use a Node runtime with node:sqlite enabled.

Cloud control-plane codes

The published cloud codes include:

CLOUD_AUTH_FAILED
CLOUD_SESSION_NOT_FOUND
CLOUD_ARTIFACT_NOT_FOUND
CLOUD_SESSION_CLOSED
CLOUD_UNSUPPORTED_METHOD
CLOUD_INVALID_REQUEST
CLOUD_MODEL_NOT_ALLOWED
CLOUD_ACTION_FAILED
CLOUD_CAPACITY_EXHAUSTED
CLOUD_RUNTIME_UNAVAILABLE
CLOUD_RUNTIME_MISMATCH
CLOUD_SESSION_STALE
CLOUD_CONTROL_PLANE_ERROR
CLOUD_CONTRACT_MISMATCH
CLOUD_PROXY_UNAVAILABLE
CLOUD_PROXY_REQUIRED
CLOUD_BILLING_LIMIT_REACHED
CLOUD_PLAN_RESTRICTED
CLOUD_RATE_LIMITED
CLOUD_BROWSER_PROFILE_NOT_FOUND
CLOUD_BROWSER_PROFILE_BUSY
CLOUD_BROWSER_PROFILE_DISABLED
CLOUD_BROWSER_PROFILE_NOT_READY
CLOUD_BROWSER_PROFILE_PROXY_UNAVAILABLE
CLOUD_BROWSER_PROFILE_SYNC_FAILED
CLOUD_INTERNAL

Fast troubleshooting

DOM actions fail

• Re-run snapshot action and use fresh counters.
• Make sure you are not mixing up element, selector, and persist.
• If you intended a saved target, use persist through the SDK instead of reusing an old element number.

Network inspection is empty

• Confirm you actually captured traffic with captureNetwork.
• Query the same workspace that created the capture.
• If you are using saved-network features locally, make sure the Node runtime has node:sqlite.
• In managed cloud mode, raw discovery records are session-scoped scratch data. Inspect or promote what you need before the runtime goes away. Local-cloud development keeps that history in the local workspace.

Recording fails

• record only supports the Playwright engine.
• record requires a headed browser.
• record does not support attach mode.
• record --provider cloud also needs OPENSTEER_CLOUD_APP_BASE_URL or --cloud-app-base-url.

Instrumentation helpers fail

• route() and interceptScript() only work on runtimes that expose instrumentation.
• If you see the runtime-availability error, switch to a local or cloud Playwright session instead of ABP or an unsupported attachment flow.

Cloud mode fails immediately

• Verify OPENSTEER_API_KEY.
• Verify OPENSTEER_BASE_URL.
• Verify OPENSTEER_CLOUD_APP_BASE_URL if you are using cloud recording.
• Do not use ABP in cloud mode.
• Do not use attach mode in cloud mode.

Browser helpers fail

opensteer.browser.status(), clone(), reset(), and delete() are local-only. clone(), reset(), and delete() also require a persistent workspace browser.