Skip to main content

Automation isn't working

Several controls can stop an automation call, and each one stops it on purpose. Work through the checks below in order. It's the order the controls are applied, so the first one that fails is your cause.

Several controls can stop an automation call, and each one stops it on purpose. Work through the checks below in order. It's the order the controls are applied, so the first one that fails is your cause.

Check 1 - Automation is switched on for the account

  1. Go to Admin > Account Settings.

  2. Make sure Automation Enabled is on.

When it's off, no automation session can start anywhere in the account, whatever else is set. Check it first, because it affects everything, and someone else may have turned it off. See Secure the account.

Check 2 - The API key is the one you expect, and it's active

  1. Run hv auth status. It shows which key the CLI is using. If it's the wrong one, run hv auth login again.

  2. In Admin > API Keys, confirm the key is active and has the USE_AUTOMATION permission.

A disabled or expired key returns ERR_API_KEY_DISABLED or ERR_API_KEY_EXPIRED.

Check 3 - The key can reach the system

A key only sees the systems its access rules match. If no rule matches, the system is invisible to the key, so it looks like the system doesn't exist, not like a permission error.

Open the key in Admin > API Keys and check that one of its rules covers the system. See API keys and their permissions.

Check 4 - The policy allows what you're trying to do

The key can reach the system but may not be allowed to do the specific thing. The capability policy on the matching rule decides.

  1. Run hv capabilities check. It lists what's granted, what needs approval, and what's denied on this session.

  2. Find the capability your command needs. The hv CLI reference lists which command needs which.

If it's denied, change the policy or use a key with a different one. See Create and use capability policies.

Check 5 - Nothing is waiting for approval

If the policy sets the capability to Human approval or Guardian, the call waits for a decision instead of failing. The command exits with code 9, and the API returns ERR_STEP_UP_REQUIRED.

  1. Run hv approvals list to see open requests and live grants for this key.

  2. To ask for approval, run the blocked command again with --request-approval and an --approval-reason. The approver sees your actual command.

  3. Run hv approvals wait <approval-uuid> until it's decided, then run the command again.

See Approve a capability request.

Check 6 - The system is online and someone is signed in

  • Offline or blocked. The API returns ERR_SERVER_OFFLINE. Check for a green dot on the Systems screen.

  • Nobody signed in. Run hv system-info. If session_state is logged_out, locked or screensaver, screenshots show a sign-in screen and typing goes nowhere. Sign a user in with hv desktop login first.

  • Can't read the screen's controls. The ui endpoint returns accessibility_available and a remediation hint when it can't read the accessibility tree. On macOS, this usually means a permission was never granted.

Check 7 - The account has hours left

A used-up plan or a reached overage limit stops new sessions. Look for ERR_ACCOUNT_PLAN_INACTIVE, ERR_BILLING_RESTRICTED or ERR_SUBSCRIPTION_EXPIRED, and check Admin > Billing. See Control what you spend.

Check 8 - You aren't calling too fast

ERR_RATE_LIMIT_EXCEEDED, with HTTP 429, means too many calls. Wait, then try again.

Still stuck?

Go to Admin > Activity Log and set Actor Type to api_key. It shows what the key actually did and where it was stopped. See The activity log.

Did this answer your question?