Skip to content

Automate browser based workflows with AI

SKY-7925 - add exception handing for vault configuration issues (#4758)

Shuchang Zheng06fe51adfa88
diff --git a/fern/openapi/skyvern_openapi.json b/fern/openapi/skyvern_openapi.json
index 2ffc0d112..f45675da0 100644
--- a/fern/openapi/skyvern_openapi.json
+++ b/fern/openapi/skyvern_openapi.json
@@ -105,7 +105,7 @@
"/v1/run/workflows": {
"post": {
"tags": [
- "Workflow Runs"
+ "Workflows"
],
"summary": "Run a workflow",
"description": "Run a workflow",
@@ -228,7 +228,7 @@
"get": {
"tags": [
"Agent",
- "Workflow Runs"
+ "Workflows"
],
"summary": "Get a run by id",
"description": "Get run information (task run, workflow run)",
@@ -334,7 +334,7 @@
"post": {
"tags": [
"Agent",
- "Workflow Runs"
+ "Workflows"
],
"summary": "Cancel a run by id",
"description": "Cancel a run (task or workflow)",
@@ -571,15 +571,10 @@
"type": "null"
}
],
- "description": "Case-insensitive substring search across: workflow title, folder name, and parameter metadata (key, description, default_value). A workflow is returned if any of these fields match. Soft-deleted parameter definitions are excluded. Takes precedence over the deprecated `title` parameter.",
- "examples": [
- "my_workflow",
- "login_url",
- "production"
- ],
+ "description": "Unified search across workflow title, folder name, and parameter metadata (key, description, default_value).",
"title": "Search Key"
},
- "description": "Case-insensitive substring search across: workflow title, folder name, and parameter metadata (key, description, default_value). A workflow is returned if any of these fields match. Soft-deleted parameter definitions are excluded. Takes precedence over the deprecated `title` parameter."
+ "description": "Unified search across workflow title, folder name, and parameter metadata (key, description, default_value)."
},
{
"name": "title",
@@ -587,12 +582,12 @@
"required": false,
"schema": {
"type": "string",
- "description": "Deprecated: use search_key instead. Falls back to title-only search if search_key is not provided.",
+ "description": "Deprecated: use search_key instead.",
"deprecated": true,
"default": "",
"title": "Title"
},
- "description": "Deprecated: use search_key instead. Falls back to title-only search if search_key is not provided.",
+ "description": "Deprecated: use search_key instead.",
"deprecated": true
},
{
@@ -1026,8 +1021,7 @@
"/v1/runs/{run_id}/retry_webhook": {
"post": {
"tags": [
- "Agent",
- "Workflow Runs"
+ "Agent"
],
"summary": "Retry run webhook",
"description": "Retry sending the webhook for a run",
@@ -1125,7 +1119,7 @@
"get": {
"tags": [
"Agent",
- "Workflow Runs"
+ "Workflows"
],
"summary": "Get run timeline",
"description": "Get timeline for a run (workflow run or task_v2 run)",
@@ -1214,158 +1208,6 @@
]
}
},
- "/v1/workflows/runs": {
- "get": {
- "tags": [
- "Workflow Runs"
- ],
- "summary": "List workflow runs",
- "description": "List workflow runs across all workflows for the current organization.\n\nResults are paginated and can be filtered by **status**, **search_key**, and **error_code**. All filters are combined with **AND** logic — a run must match every supplied filter to be returned.\n\n### search_key\n\nA case-insensitive substring search that matches against **any** of the following fields:\n\n| Searched field | Description |\n|---|---|\n| `workflow_run_id` | The unique run identifier (e.g. `wr_123…`) |\n| Parameter **key** | The `key` of any workflow parameter definition associated with the run |\n| Parameter **description** | The `description` of any workflow parameter definition |\n| Run parameter **value** | The actual value supplied for any parameter when the run was created |\n| `extra_http_headers` | Extra HTTP headers attached to the run (searched as raw JSON text) |\n\nSoft-deleted parameter definitions are excluded from key/description matching. A run is returned if **any** of the fields above contain the search term.\n\n### error_code\n\nAn **exact-match** filter against the `error_code` field inside each task's `errors` JSON array. A run matches if **any** of its tasks contains an error object with a matching `error_code` value. Error codes are user-defined strings set during workflow execution (e.g. `INVALID_CREDENTIALS`, `LOGIN_FAILED`, `CAPTCHA_DETECTED`).\n\n### Combining filters\n\nAll query parameters use AND logic:\n- `?status=failed` — only failed runs\n- `?status=failed&error_code=LOGIN_FAILED` — failed runs **and** have a LOGIN_FAILED error\n- `?status=failed&error_code=LOGIN_FAILED&search_key=prod_credential` — all three conditions must match",
- "operationId": "get_workflow_runs_v1_workflows_runs_get",
- "parameters": [
- {
- "name": "page",
- "in": "query",
- "required": false,
- "schema": {
- "type": "integer",
- "minimum": 1,
- "description": "Page number for pagination.",
- "default": 1,
- "title": "Page"
- },
- "description": "Page number for pagination."
- },
- {
- "name": "page_size",
- "in": "query",
- "required": false,
- "schema": {
- "type": "integer",
- "minimum": 1,
- "description": "Number of runs to return per page.",
- "default": 10,
- "title": "Page Size"
- },
- "description": "Number of runs to return per page."
- },
- {
- "name": "status",
- "in": "query",
- "required": false,
- "schema": {
- "anyOf": [
- {
- "type": "array",
- "items": {
- "$ref": "#/components/schemas/WorkflowRunStatus"
- }
- },
- {
- "type": "null"
- }
- ],
- "description": "Filter by one or more run statuses.",
- "title": "Status"
- },
- "description": "Filter by one or more run statuses."
- },
- {
- "name": "search_key",
- "in": "query",
- "required": false,
- "schema": {
- "anyOf": [
- {
- "type": "string",
- "maxLength": 500
- },
- {
- "type": "null"
- }
- ],
- "description": "Case-insensitive substring search across: workflow run ID, parameter key, parameter description, run parameter value, and extra HTTP headers. A run is returned if any of these fields match. Soft-deleted parameter definitions are excluded from key/description matching.",
- "examples": [
- "login_url",
- "credential_value",
- "wr_abc123"
- ],
- "title": "Search Key"
- },
- "description": "Case-insensitive substring search across: workflow run ID, parameter key, parameter description, run parameter value, and extra HTTP headers. A run is returned if any of these fields match. Soft-deleted parameter definitions are excluded from key/description matching."
- },
- {
- "name": "error_code",
- "in": "query",
- "required": false,
- "schema": {
- "anyOf": [
- {
- "type": "string",
- "maxLength": 500
- },
- {
- "type": "null"
- }
- ],
- "description": "Exact-match filter on the error_code field inside each task's errors JSON array. A run matches if any of its tasks contains an error with a matching error_code. Error codes are user-defined strings set during workflow execution.",
- "examples": [
- "INVALID_CREDENTIALS",
- "LOGIN_FAILED",
- "CAPTCHA_DETECTED"
- ],
- "title": "Error Code"
- },
- "description": "Exact-match filter on the error_code field inside each task's errors JSON array. A run matches if any of its tasks contains an error with a matching error_code. Error codes are user-defined strings set during workflow execution."
- },
- {
- "name": "x-api-key",
- "in": "header",
- "required": false,
- "schema": {
- "anyOf": [
- {
- "type": "string"
- },
- {
- "type": "null"
- }
- ],
- "description": "Skyvern API key for authentication. API key can be found at https://app.skyvern.com/settings.",
- "title": "X-Api-Key"
- },
- "description": "Skyvern API key for authentication. API key can be found at https://app.skyvern.com/settings."
- }
- ],
- "responses": {
- "200": {
- "description": "Successful Response",
- "content": {
- "application/json": {
- "schema": {
- "type": "array",
- "items": {
- "$ref": "#/components/schemas/WorkflowRun"
- },
- "title": "Response Get Workflow Runs V1 Workflows Runs Get"
- }
- }
- }
- },
- "422": {
- "description": "Validation Error",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/HTTPValidationError"
- }
- }
- }
- }
- },
- "x-fern-sdk-method-name": "get_workflow_runs"
- }
- },
"/v1/workflows/{workflow_permanent_id}": {
"get": {
"tags": [
@@ -4121,11 +3963,6 @@
],
"title": "Has Mini Agent"
},
- "skip_auto_complete_tab": {
- "type": "boolean",
- "title": "Skip Auto Complete Tab",
- "default": false
- },
"created_at": {
"anyOf": [
{
@@ -8851,8 +8688,7 @@
"csv",
"excel",
"pdf",
- "image",
- "docx"
+ "image"
],
"title": "FileType"
},
@@ -17899,326 +17735,6 @@
"type": "object",
"title": "WorkflowRequest"
},
- "WorkflowRun": {
- "properties": {
- "workflow_run_id": {
- "type": "string",
- "title": "Workflow Run Id"
- },
- "workflow_id": {
- "type": "string",
- "title": "Workflow Id"
- },
- "workflow_permanent_id": {
- "type": "string",
- "title": "Workflow Permanent Id"
- },
- "organization_id": {
- "type": "string",
- "title": "Organization Id"
- },
- "browser_session_id": {
- "anyOf": [
- {
- "type": "string"
- },
- {
- "type": "null"
- }
- ],
- "title": "Browser Session Id"
- },
- "browser_profile_id": {
- "anyOf": [
- {
- "type": "string"
- },
- {
- "type": "null"
- }
- ],
- "title": "Browser Profile Id"
- },
- "debug_session_id": {
- "anyOf": [
- {
- "type": "string"
- },
- {
- "type": "null"
- }
- ],
- "title": "Debug Session Id"
- },
- "status": {
- "$ref": "#/components/schemas/WorkflowRunStatus"
- },
- "extra_http_headers": {
- "anyOf": [
- {
- "additionalProperties": {
- "type": "string"
- },
- "type": "object"
- },
- {
- "type": "null"
- }
- ],
- "title": "Extra Http Headers"
- },
- "proxy_location": {
- "anyOf": [
- {
- "$ref": "#/components/schemas/ProxyLocation"
- },
- {
- "$ref": "#/components/schemas/GeoTarget"
- },
- {
- "additionalProperties": true,
- "type": "object"
- },
- {
- "type": "null"
- }
- ],
- "title": "Proxy Location"
- },
- "webhook_callback_url": {
- "anyOf": [
- {
- "type": "string"
- },
- {
- "type": "null"
- }
- ],
- "title": "Webhook Callback Url"
- },
- "webhook_failure_reason": {
- "anyOf": [
- {
- "type": "string"
- },
- {
- "type": "null"
- }
- ],
- "title": "Webhook Failure Reason"
- },
- "totp_verification_url": {
- "anyOf": [
- {
- "type": "string"
- },
- {
- "type": "null"
- }
- ],
- "title": "Totp Verification Url"
- },
- "totp_identifier": {
- "anyOf": [
- {
- "type": "string"
- },
- {
- "type": "null"
- }
- ],
- "title": "Totp Identifier"
- },
- "failure_reason": {
- "anyOf": [
- {
- "type": "string"
- },
- {
- "type": "null"
- }
- ],
- "title": "Failure Reason"
- },
- "parent_workflow_run_id": {
- "anyOf": [
- {
- "type": "string"
- },
- {
- "type": "null"
- }
- ],
- "title": "Parent Workflow Run Id"
- },
- "workflow_title": {
- "anyOf": [
- {
- "type": "string"
- },
- {
- "type": "null"
- }
- ],
- "title": "Workflow Title"
- },
- "max_screenshot_scrolls": {
- "anyOf": [
- {
- "type": "integer"
- },
- {
- "type": "null"
- }
- ],
- "title": "Max Screenshot Scrolls"
- },
- "browser_address": {
- "anyOf": [
- {
- "type": "string"
- },
- {
- "type": "null"
- }
- ],
- "title": "Browser Address"
- },
- "run_with": {
- "anyOf": [
- {
- "type": "string"
- },
- {
- "type": "null"
- }
- ],
- "title": "Run With"
- },
- "script_run": {
- "anyOf": [
- {
- "$ref": "#/components/schemas/ScriptRunResponse"
- },
- {
- "type": "null"
- }
- ]
- },
- "job_id": {
- "anyOf": [
- {
- "type": "string"
- },
- {
- "type": "null"
- }
- ],
- "title": "Job Id"
- },
- "depends_on_workflow_run_id": {
- "anyOf": [
- {
- "type": "string"
- },
- {
- "type": "null"
- }
- ],
- "title": "Depends On Workflow Run Id"
- },
- "sequential_key": {
- "anyOf": [
- {
- "type": "string"
- },
- {
- "type": "null"
- }
- ],
- "title": "Sequential Key"
- },
- "ai_fallback": {
- "anyOf": [
- {
- "type": "boolean"
- },
- {
- "type": "null"
- }
- ],
- "title": "Ai Fallback"
- },
- "code_gen": {
- "anyOf": [
- {
- "type": "boolean"
- },
- {
- "type": "null"
- }
- ],
- "title": "Code Gen"
- },
- "queued_at": {
- "anyOf": [
- {
- "type": "string",
- "format": "date-time"
- },
- {
- "type": "null"
- }
- ],
- "title": "Queued At"
- },
- "started_at": {
- "anyOf": [
- {
- "type": "string",
- "format": "date-time"
- },
- {
- "type": "null"
- }
- ],
- "title": "Started At"
- },
- "finished_at": {
- "anyOf": [
- {
- "type": "string",
- "format": "date-time"
- },
- {
- "type": "null"
- }
- ],
- "title": "Finished At"
- },
- "created_at": {
- "type": "string",
- "format": "date-time",
- "title": "Created At"
- },
- "modified_at": {
- "type": "string",
- "format": "date-time",
- "title": "Modified At"
- }
- },
- "type": "object",
- "required": [
- "workflow_run_id",
- "workflow_id",
- "workflow_permanent_id",
- "organization_id",
- "status",
- "created_at",
- "modified_at"
- ],
- "title": "WorkflowRun"
- },
"WorkflowRunBlock": {
"properties": {
"workflow_run_block_id": {
@@ -19161,21 +18677,6 @@
],
"title": "WorkflowRunResponse"
},
- "WorkflowRunStatus": {
- "type": "string",
- "enum": [
- "created",
- "queued",
- "running",
- "failed",
- "terminated",
- "canceled",
- "timed_out",
- "completed",
- "paused"
- ],
- "title": "WorkflowRunStatus"
- },
"WorkflowRunTimeline": {
"properties": {
"type": {
diff --git a/skyvern/exceptions.py b/skyvern/exceptions.py
index ec0789df2..e30302f79 100644
--- a/skyvern/exceptions.py
+++ b/skyvern/exceptions.py
@@ -426,6 +426,14 @@ class CredentialParameterNotFoundError(SkyvernException):
super().__init__(f"Could not find credential parameter: {credential_parameter_id}")
+class CredentialVaultNotConfiguredError(SkyvernException):
+ def __init__(self, vault_type: str, credential_id: str) -> None:
+ super().__init__(
+ f"Credential vault service '{vault_type}' is not configured. "
+ f"Credential {credential_id} was found in DB but cannot be resolved."
+ )
+
+
class UnknownElementTreeFormat(SkyvernException):
def __init__(self, fmt: str) -> None:
super().__init__(f"Unknown element tree format {fmt}")
diff --git a/skyvern/forge/sdk/workflow/context_manager.py b/skyvern/forge/sdk/workflow/context_manager.py
index cb914e21a..f81ce8e19 100644
--- a/skyvern/forge/sdk/workflow/context_manager.py
+++ b/skyvern/forge/sdk/workflow/context_manager.py
@@ -11,6 +11,7 @@ from skyvern.exceptions import (
AzureConfigurationError,
BitwardenBaseError,
CredentialParameterNotFoundError,
+ CredentialVaultNotConfiguredError,
ImaginarySecretValue,
SkyvernException,
WorkflowRunContextNotInitialized,
@@ -396,7 +397,7 @@ class WorkflowRunContext:
vault_type = db_credential.vault_type or CredentialVaultType.BITWARDEN
credential_service = app.CREDENTIAL_VAULT_SERVICES.get(vault_type)
if credential_service is None:
- raise CredentialParameterNotFoundError(credential_id)
+ raise CredentialVaultNotConfiguredError(vault_type=vault_type.value, credential_id=credential_id)
credential_item = await credential_service.get_credential_item(db_credential)
credential = credential_item.credential