Skip to main content

Overview

Nova Act provides a comprehensive error hierarchy for handling different failure scenarios. All errors during act() execution inherit from ActError, which itself inherits from NovaActError.
from nova_act import NovaAct, ActError, ActTimeoutError

try:
    with NovaAct(starting_page="https://example.com") as nova:
        nova.act("Complete task", timeout=30)
except ActTimeoutError:
    print("Task timed out")
except ActError as e:
    print(f"Act failed: {e.message}")
    print(f"Steps executed: {e.metadata.num_steps_executed}")

Base Errors

NovaActError

Base exception class for all Nova Act errors.
from nova_act import NovaActError

try:
    # NovaAct operations
    pass
except NovaActError as e:
    print(f"Nova Act error: {e}")

ActError

Base class for all errors encountered during act() execution. Contains metadata about the execution context.
from nova_act import ActError

try:
    with NovaAct(starting_page="https://example.com") as nova:
        nova.act("Complete task")
except ActError as e:
    print(f"Error: {e.message}")
    if e.metadata:
        print(f"Session: {e.metadata.session_id}")
        print(f"Act ID: {e.metadata.act_id}")
        print(f"Steps: {e.metadata.num_steps_executed}")

Attributes

message
str
Human-readable error message.
metadata
ActMetadata | None
Metadata about the act execution context, including session_id, act_id, and step count.

Execution Errors

Errors related to client-side execution issues.

ActExecutionError

Indicates an error encountered during client execution.
from nova_act import ActExecutionError

try:
    nova.act("Complete task")
except ActExecutionError as e:
    print(f"Execution error: {e}")

ActCanceledError

Indicates the client received a cancel signal and stopped.
from nova_act import ActCanceledError

try:
    nova.act("Long running task")
except ActCanceledError:
    print("User canceled the operation")
Default message: “Act Canceled.”

ActActuationError

Indicates the client failed to actuate a given command from the agent.
from nova_act import ActActuationError

try:
    nova.act("Click invalid element")
except ActActuationError as e:
    print(f"Actuation failed: {e.message}")
Default message: “Encountered error actuating model actions.”

ActTimeoutError

Indicates an act call timed out.
from nova_act import ActTimeoutError

try:
    nova.act("Complex task", timeout=10)
except ActTimeoutError:
    print("Task exceeded timeout")
Default message: “Timed out; try increasing the ‘timeout’ kwarg on the ‘act’ call”

ActStateGuardrailError

Indicates a client-provided agent state guardrail triggered.
from nova_act import ActStateGuardrailError, GuardrailDecision

def my_guardrail(state):
    if "blocked.com" in state.browser_url:
        return GuardrailDecision.BLOCK
    return GuardrailDecision.PASS

try:
    with NovaAct(starting_page="https://example.com", 
                 state_guardrail=my_guardrail) as nova:
        nova.act("Navigate")
except ActStateGuardrailError:
    print("Blocked by guardrail")
Default message: “Blocked by agent state guardrail”

Agent Errors

Errors indicating the agent cannot complete the requested task.

ActAgentError

Indicates the provided prompt cannot be completed in the given configuration.
from nova_act import ActAgentError

try:
    nova.act("Impossible task")
except ActAgentError as e:
    print(f"Agent error: {e.message}")

ActAgentFailed

Indicates the model raised an error because it could not complete the request.
from nova_act import ActAgentFailed

try:
    nova.act("Find element that doesn't exist")
except ActAgentFailed:
    print("Agent explicitly failed")
Default message: “The requested action was not possible”

ActExceededMaxStepsError

Indicates an Act session exceeded the maximum allowed steps.
from nova_act import ActExceededMaxStepsError

try:
    nova.act("Complex task", max_steps=5)
except ActExceededMaxStepsError:
    print("Task required too many steps")
Default message: “Allowed Steps Exceeded”

Model Generation Errors

Errors related to model output and tool invocation.

ActInvalidModelGenerationError

Indicates the Act model failed or produced invalid output.
from nova_act import ActInvalidModelGenerationError

try:
    result = nova.act_get("Get data", schema={"type": "object"})
except ActInvalidModelGenerationError as e:
    print(f"Invalid model output: {e.message}")
    if e.raw_response:
        print(f"Raw response: {e.raw_response}")
Default message: “The model output could not be processed. Please try a different request.”

Attributes

raw_response
str | None
The raw response from the model, if available.

ActInvalidToolError

Indicates the model attempted to call an unknown tool.
from nova_act import ActInvalidToolError

try:
    nova.act("Use unknown tool")
except ActInvalidToolError:
    print("Model called non-existent tool")
Default message: “The requested tool does not exist.”

ActInvalidToolSchemaError

Indicates a tool call failed validation against the tool schema.
from nova_act import ActInvalidToolSchemaError

try:
    nova.act("Call tool with wrong arguments")
except ActInvalidToolSchemaError:
    print("Tool arguments didn't match schema")
Default message: “Tool arguments did not match the expected schema.”

Tool Execution Errors

ActToolError

Indicates a failure running a tool.
from nova_act import ActToolError

try:
    nova.act("Use failing tool")
except ActToolError:
    print("Tool execution failed")
Default message: “Failed to invoke a tool.”

ActMCPError

Indicates a failure running an MCP-provided tool.
from nova_act import ActMCPError

try:
    nova.act("Use MCP tool")
except ActMCPError:
    print("MCP tool failed")
Default message: “Failed to invoke MCP tool.”

API Errors

Errors related to communication with NovaAct services.

ActAPIError

Base class for errors caused by a breach of contract between client/server.
from nova_act import ActAPIError

try:
    nova.act("Task")
except ActAPIError as e:
    print(f"API error: {e.message}")
    print(f"Status code: {e.status_code}")
    print(f"Request ID: {e.request_id}")

Attributes

request_id
str | None
The request ID from the server.
status_code
int | None
HTTP status code of the response.
raw_response
str | None
Raw response body from the server.

ActClientError

Errors caused by bad requests to NovaAct Service. Indicates that users may retry with a different request.
from nova_act import ActClientError

try:
    nova.act("Invalid request")
except ActClientError as e:
    print(f"Client error: {e.message}")
    print(f"Fix your request and try again")
Default message: “Client error calling NovaAct Service.”

ActBadRequestError

Indicates a bad request to /step endpoint.
from nova_act import ActBadRequestError

try:
    nova.act("Malformed request")
except ActBadRequestError:
    print("Request was malformed")
Default message: “Bad request”

ActGuardrailsError

Indicates an Act request was blocked by the agent guardrails system.
from nova_act import ActGuardrailsError

try:
    nova.act("Unsafe action")
except ActGuardrailsError:
    print("Request blocked by server guardrails")
Default message: “I’m sorry, but I can’t engage in unsafe or inappropriate actions. Please try a different request.”

ActRateLimitExceededError

Indicates a request for an Act session was throttled.
from nova_act import ActRateLimitExceededError

try:
    nova.act("Task")
except ActRateLimitExceededError:
    print("Rate limit exceeded, try again later")
Suggests migrating to AWS Nova Act service for dedicated quota.

ActRequestThrottledError

Indicates a request was throttled due to too many requests in a short time.
from nova_act import ActRequestThrottledError
import time

try:
    nova.act("Task")
except ActRequestThrottledError:
    print("Throttled, waiting before retry...")
    time.sleep(5)

ActDailyQuotaExceededError

Indicates a request was rejected as the user’s daily quota has been exceeded.
from nova_act import ActDailyQuotaExceededError

try:
    nova.act("Task")
except ActDailyQuotaExceededError:
    print("Daily quota exceeded")

ActServerError

Error caused by bad responses from NovaAct Service. Indicates an issue with the service.
from nova_act import ActServerError

try:
    nova.act("Task")
except ActServerError as e:
    print(f"Server error: {e.message}")
    print("Please report to customer support")
Default message: “Error calling NovaAct Service.”

ActBadResponseError

Indicates a bad response from the /step endpoint.
from nova_act import ActBadResponseError

try:
    nova.act("Task")
except ActBadResponseError:
    print("Received malformed response from server")
Default message: “Bad Response”

ActServiceUnavailableError

Indicates the /step endpoint is currently unavailable.
from nova_act import ActServiceUnavailableError
import time

try:
    nova.act("Task")
except ActServiceUnavailableError:
    print("Service unavailable, retrying...")
    time.sleep(10)
Default message: “NovaAct Service Unavailable”

ActInternalServerError

Indicates an internal server error occurred while processing an Act request.
from nova_act import ActInternalServerError

try:
    nova.act("Task")
except ActInternalServerError:
    print("Internal server error")
Default message: “Internal Server Error”

Human Input Errors

NoHumanInputToolAvailable

Indicates the model requested human input but no callbacks were provided.
from nova_act import NoHumanInputToolAvailable

try:
    # NovaAct without human_input_callbacks
    nova.act("Task requiring human input")
except NoHumanInputToolAvailable:
    print("Need to provide human_input_callbacks")
Default message: “Human input required to proceed. Implement and provide human_input_callbacks.”

ApproveCanceledError

Indicates the client received a cancel response during human approval.
from nova_act import ApproveCanceledError

try:
    nova.act("Task with approval")
except ApproveCanceledError:
    print("User denied approval")
Default message: “Act Canceled during Human Approval.”

UiTakeoverCanceledError

Indicates the client received a cancel signal during human UI takeover.
from nova_act import UiTakeoverCanceledError

try:
    nova.act("Task with UI takeover")
except UiTakeoverCanceledError:
    print("User canceled during UI takeover")
Default message: “Act Canceled during Human UI Takeover.”

NovaAct Lifecycle Errors

StartFailed

Raised when the NovaAct client fails to start.
from nova_act import NovaAct, StartFailed

try:
    nova = NovaAct(starting_page="invalid://url")
    nova.start()
except StartFailed as e:
    print(f"Failed to start: {e}")

StopFailed

Raised when the NovaAct client fails to stop cleanly.
from nova_act import NovaAct, StopFailed

try:
    nova.stop()
except StopFailed as e:
    print(f"Failed to stop: {e}")

ValidationFailed

Raised when input validation fails.
from nova_act import NovaAct, ValidationFailed

try:
    nova = NovaAct(
        starting_page="https://example.com",
        screen_width=-100  # Invalid
    )
except ValidationFailed as e:
    print(f"Validation error: {e}")

ClientNotStarted

Raised when attempting to use NovaAct before calling start().
from nova_act import NovaAct, ClientNotStarted

try:
    nova = NovaAct(starting_page="https://example.com")
    nova.act("Task")  # Error: not started
except ClientNotStarted:
    print("Must call start() first")
    nova.start()

AuthError

Raised when authentication fails or is misconfigured.
from nova_act import Workflow, AuthError

try:
    workflow = Workflow(
        model_id="nova-act-latest",
        boto_session_kwargs={},
        nova_act_api_key="key"  # Can't use both
    )
except AuthError as e:
    print(f"Auth error: {e}")

Deprecated Errors

The following errors are deprecated and maintained for backward compatibility only.

ActModelError (Deprecated)

Deprecated since 2.1.0. Use ActInvalidModelGenerationError instead.

ActPromptError (Deprecated)

Deprecated since 2.1.0. Rolled into ActClientError.

ActDispatchError (Deprecated)

Deprecated since 2.1.0. No longer raised as Chrome extension is deprecated.

ActProtocolError (Deprecated)

Deprecated since 2.1.0. Roughly correlates with ActAPIError.

ActInvalidInputError (Deprecated)

Deprecated since 2.1.0. Rolled into ActBadRequestError.

Error Handling Best Practices

Catch Specific Errors

from nova_act import (
    NovaAct,
    ActTimeoutError,
    ActRateLimitExceededError,
    ActAgentFailed,
    ActError
)

with NovaAct(starting_page="https://example.com") as nova:
    try:
        nova.act("Complete task", timeout=30)
    except ActTimeoutError:
        print("Task timed out, consider increasing timeout")
    except ActRateLimitExceededError:
        print("Rate limited, wait before retrying")
    except ActAgentFailed:
        print("Agent couldn't complete task, try different prompt")
    except ActError as e:
        print(f"Other act error: {e}")

Access Error Metadata

from nova_act import NovaAct, ActError

with NovaAct(starting_page="https://example.com") as nova:
    try:
        nova.act("Task")
    except ActError as e:
        if e.metadata:
            print(f"Failed after {e.metadata.num_steps_executed} steps")
            print(f"Session: {e.metadata.session_id}")
            print(f"Prompt: {e.metadata.prompt}")

Retry Logic

from nova_act import NovaAct, ActRequestThrottledError, ActServerError
import time

def act_with_retry(nova, prompt, max_retries=3):
    for attempt in range(max_retries):
        try:
            return nova.act(prompt)
        except ActRequestThrottledError:
            if attempt < max_retries - 1:
                wait_time = 2 ** attempt  # Exponential backoff
                print(f"Throttled, waiting {wait_time}s...")
                time.sleep(wait_time)
            else:
                raise
        except ActServerError:
            if attempt < max_retries - 1:
                print(f"Server error, retrying...")
                time.sleep(5)
            else:
                raise

with NovaAct(starting_page="https://example.com") as nova:
    result = act_with_retry(nova, "Complete task")

Build docs developers (and LLMs) love