Common Errors

Symptom	Cause	Fix
CLOUD_AUTH_FAILED	Invalid or missing API key	Check OPENSTEER_API_KEY value and header format
CLOUD_CONTRACT_MISMATCH	SDK version mismatch	Update opensteer package to latest
CLOUD_CAPACITY_FULL	No runtime slots available	Retry after backoff, or contact support
CLOUD_UNSUPPORTED_METHOD	Method not available in cloud	Use a supported alternative (see below)
Counter actions failing	Stale snapshot	Re-run snapshot action before counter-based actions
Selectors not replaying	Namespace mismatch	Ensure --name (CLI) matches name (SDK)
Empty extraction results	Wrong snapshot mode	Use snapshot extraction before extract

Unsupported Cloud Methods

These methods throw CLOUD_UNSUPPORTED_METHOD:

• Opensteer.from(page) — use launch() instead
• uploadFile() — not available in cloud
• exportCookies() — not available in cloud
• importCookies() — not available in cloud

CUA agent (agent.execute) is supported in cloud mode after launch().

Debug Logging

Enable detailed logging:

OPENSTEER_DEBUG=true opensteer snapshot action

Or in SDK:

OPENSTEER_DEBUG=true node my-script.ts

CLI Troubleshooting

1. Run opensteer status to verify session state
2. Re-run opensteer snapshot action before counter-based actions
3. Enable OPENSTEER_DEBUG=true for detailed errors
4. Ensure namespace consistency: --name in CLI must match name in SDK
5. Refresh cached descriptions if replay breaks after UI changes

Stability Tips

• Prefer OpenSteer high-level actions over raw Playwright calls (they include stability handling)
• Use explicit waits only at transition boundaries or for async UI updates
• Re-snapshot before counter-based actions after navigation or significant DOM changes
• Keep waits deterministic — tie them to visible cues, not timers