Error Types

All Opensteer errors extend OpensteerProtocolError:

class OpensteerProtocolError extends Error {
  code: string;
  retriable: boolean;
  details?: Record<string, unknown>;
}

Action Failure Codes

Code	Description
TARGET_NOT_FOUND	Target element not found in DOM
TARGET_UNAVAILABLE	Target element is not available
TARGET_STALE	Target element reference is stale
TARGET_AMBIGUOUS	Multiple elements match the target
NOT_VISIBLE	Element is not visible
NOT_ENABLED	Element is not enabled/interactable
NOT_EDITABLE	Element is not editable
INVALID_TARGET	Invalid target specification
INVALID_OPTIONS	Invalid action options
ACTION_TIMEOUT	Action timed out

Protocol Error Codes

Code	Description
invalid-request	Malformed request
invalid-argument	Invalid argument value
not-found	Resource not found
timeout	Operation timed out
navigation-failed	Page navigation failed
session-closed	Session was closed
page-closed	Page was closed
unsupported-operation	Operation not supported
operation-failed	Operation failed
internal	Internal error

Cloud Error Codes

Code	Description
CLOUD_AUTH_FAILED	Invalid or missing API key
CLOUD_SESSION_NOT_FOUND	Session expired or not found
CLOUD_SESSION_CLOSED	Session was closed
CLOUD_UNSUPPORTED_METHOD	Method not available in cloud mode
CLOUD_CAPACITY_EXHAUSTED	No capacity available
CLOUD_RATE_LIMITED	Too many requests
CLOUD_INVALID_REQUEST	Invalid request to cloud API
CLOUD_ACTION_FAILED	Cloud action execution failed
CLOUD_CONTRACT_MISMATCH	SDK/cloud version mismatch
CLOUD_INTERNAL	Internal cloud error

Troubleshooting

"Target not found" errors (TARGET_NOT_FOUND)

• Re-snapshot before every action after page changes
• Verify the counter exists in the snapshot HTML
• Use description for more resilient targeting

"Session closed" errors (session-closed)

• Ensure --workspace is consistent across commands
• Check opensteer status --workspace <id>
• The session may have timed out — re-open it

"Navigation failed" errors (navigation-failed)

• Check the URL is accessible
• Some sites block automated browsers — try with a persistent profile
• Enable debug logging: OPENSTEER_DEBUG=true

Debug Mode

Enable verbose logging:

OPENSTEER_DEBUG=true npx opensteer open https://example.com --workspace demo

Common FAQ

Local vs Cloud mode? Local runs a browser on your machine. Cloud uses Opensteer Cloud's managed browsers. Use local for development, cloud for production/CI.

Counters changed between snapshots? Counters reset on every snapshot. Always use counters from the most recent snapshot.

Actions fail in headless mode? Some sites detect headless browsers. Try --browser persistent with a real profile, or set OPENSTEER_HEADLESS=false for debugging.

CI/non-interactive environments? Always pass explicit --workspace and --root-dir. Use --headless. Re-snapshot before every counter-based action.