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
Human-readable error message.
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
The raw response from the model, if available.
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.”
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.”
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
The request ID from the server.
HTTP status code of the response.
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”
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.
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}")
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")