Skip to main content

​
Troubleshooting

Check these in order:
  1. Run status — Use get_run(run_id) to see the status and failure_reason
  2. Timeline — Use get_run_timeline(run_id) to find which block failed
  3. Artifacts — Check screenshot_final to see where it stopped, and recording to watch what happened
Common causes:
  • terminated — The AI couldn’t complete the goal (CAPTCHA, login blocked, element not found)
  • timed_out — Exceeded max_steps. Increase it or simplify the task
  • failed — System error (browser crash, network failure)
See the Troubleshooting Guide for detailed steps.
Multiple similar elements on the page can confuse the AI. Fix this by:
  1. Add visual context — “Click the blue Submit button at the bottom of the form”
  2. Reference surrounding text — “Click Download in the row that says ‘January 2024’”
  3. Be specific about position — “Click the first result” or “Click the link in the header”
Check the llm_response_parsed artifact to see what action the AI decided to take.
Tasks time out when they exceed max_steps (default: 50). This happens when:
  • The task is too complex for the step limit
  • The AI gets stuck in a navigation loop
  • Missing completion criteria causes infinite attempts
Fixes:
  • Increase max_steps in your task parameters
  • Add explicit completion criteria: “COMPLETE when you see ‘Order confirmed’”
  • Break complex tasks into multiple workflow blocks
Elements may not be detected if they:
  • Load dynamically after the page appears
  • Are inside an iframe
  • Require scrolling to become visible
  • Use unusual rendering (canvas, shadow DOM)
Fixes:
  • Add max_screenshot_scrolls to capture lazy-loaded content
  • Describe elements visually rather than by technical properties
  • Add explicit wait or scroll instructions in your prompt
Check the screenshot_final artifact to verify the AI ended on the right page.Common causes:
  • Prompt was ambiguous about what to extract
  • data_extraction_schema descriptions weren’t specific enough
  • Multiple similar elements and the AI picked the wrong one
Fixes:
  • Add specific descriptions: "description": "The price in USD, without currency symbol"
  • Add visual hints: “The price is displayed in bold below the product title”

​
Workflows

Define parameters in the workflow editor, then pass them when starting a run:
result = await client.run_workflow(
    workflow_id="wpid_123456",
    parameters={
        "url": "https://example.com",
        "username": "user@example.com"
    }
)
Parameters are available in prompts using {{ parameter_name }} syntax. See Workflow Parameters for details.
  1. Store credentials — Go to Settings > Credentials and add your login
  2. Reference in workflow — Select the credential in the Login block’s credential dropdown
  3. Never hardcode — Don’t put passwords directly in prompts
The AI will automatically fill the credential fields when it encounters a login form. See Credentials for setup instructions.
Skyvern doesn’t have built-in scheduling yet. Use external schedulers like:
  • Cron jobs — Call the Skyvern API on a schedule
  • Zapier/Make — Trigger workflows from automation platforms
  • Your backend — Integrate scheduling into your application
Set up a webhook to get notified when scheduled runs complete.
Make sure you’re using the parameter placeholder syntax correctly:
  • Correct: {{ parameter_name }}
  • Wrong: {parameter_name} or $parameter_name
Also verify:
  • The parameter name matches exactly (case-sensitive)
  • The parameter is defined in the workflow’s parameter list
  • You’re passing the parameter when starting the run, not after
Use the “Run Sequentially” option with a credential key:
  1. Enable “Run Sequentially” in workflow settings
  2. Set the sequential key to your credential identifier
  3. Skyvern will queue runs that share the same credential
This prevents concurrent logins that could trigger security blocks.

​
Configuration

Go to Settings in the Skyvern Cloud UI. Your API key is displayed there.For local installations, run skyvern init to generate a local API key, which will be saved in your .env file.
Cloud: The model is managed by Skyvern. Contact support for custom model requirements.Self-hosted: Run skyvern init llm to reconfigure, or set these environment variables:
  • LLM_KEY — Primary model (e.g., OPENAI_GPT4O, ANTHROPIC_CLAUDE_SONNET)
  • SECONDARY_LLM_KEY — Optional lightweight model for faster operations
Set proxy_location when running a task:
result = await client.run_task(
    prompt="...",
    url="https://example.com",
    proxy_location="RESIDENTIAL_US"  # or RESIDENTIAL_ISP for static IPs
)
Available locations include RESIDENTIAL_US, RESIDENTIAL_UK, RESIDENTIAL_ISP, and more. Use RESIDENTIAL_ISP for sites that require consistent IP addresses.
Yes. Contact support to increase the limit for your account. Higher limits may incur additional costs.Alternatively, break complex tasks into multiple workflow blocks, each with its own step budget.

​
API & Integration

Check the run status in a loop:
while True:
    run = await client.get_run(run_id)
    if run.status in ["completed", "failed", "terminated", "timed_out", "canceled"]:
        break
    await asyncio.sleep(5)
Or use webhooks to get notified when runs complete without polling.
The extracted data is in run.output:
run = await client.get_run(run_id)
print(run.output)  # {"field1": "value1", "field2": "value2"}
For downloaded files, check run.downloaded_files which contains signed URLs.
The recording URL is included in the run response:
run = await client.get_run(run_id)
print(run.recording_url)  # https://skyvern-artifacts.s3.amazonaws.com/.../recording.webm
Note: Signed URLs expire after 24 hours. Request fresh URLs if expired.
Use the run_workflow method:
result = await client.run_workflow(
    workflow_id="wpid_123456",
    parameters={"key": "value"}
)
print(result.run_id)  # wr_789012
The workflow starts asynchronously. Poll the run status or configure a webhook to track completion.

​
Authentication & Credentials

Check these common causes:
  1. Credentials expired — Verify username/password in your credential store
  2. CAPTCHA appeared — Use a browser profile with an existing session
  3. MFA required — Configure TOTP if the site requires 2FA
  4. Site detected automation — Use RESIDENTIAL_ISP proxy for trusted IPs
Watch the recording artifact to see exactly what happened during login.
Options to bypass CAPTCHAs:
  1. Browser profile — Create a profile with an authenticated session that skips login entirely
  2. Human interaction block — Pause the workflow for manual CAPTCHA solving
  3. Residential proxy — Use RESIDENTIAL_ISP for static IPs that sites trust more
Skyvern has built-in CAPTCHA solving for common types, but some sites use advanced anti-bot measures.
  1. Go to Settings > Credentials
  2. Create a new TOTP credential with your authenticator secret
  3. Reference the TOTP credential in your workflow’s login block
The AI will automatically fetch and enter the TOTP code when it encounters a 2FA prompt. See TOTP Setup for detailed instructions.
Email OTP requires an external integration:
  1. Set up an email listener (Zapier, custom webhook, etc.)
  2. When the OTP arrives, send it back to Skyvern via the API
  3. Use a Human Interaction block to wait for the code
Alternatively, check if the site supports TOTP authenticators, which Skyvern handles natively.

​
Browser & Proxy

Sites may detect automation through:
  • IP reputation (datacenter IPs are often blocked)
  • Browser fingerprinting
  • Rate limiting
Fixes:
  • Use RESIDENTIAL_ISP proxy for consistent, trusted IPs
  • Create a browser profile with an existing authenticated session
  • Slow down requests by adding explicit waits in your prompt
Use browser profiles:
  1. Create a browser profile in Settings > Browser Profiles
  2. Log in manually or via a workflow
  3. Reference the browser_profile_id in subsequent runs
The profile preserves cookies, localStorage, and session state across runs.
Yes, for self-hosted installations:
skyvern init  # Choose "connect to existing Chrome" option
skyvern run server
This connects to Chrome running on your machine, useful for debugging or accessing internal tools.
This usually indicates high load or network issues:
  • Wait a few seconds and retry
  • Check your rate limits
  • For self-hosted: verify your infrastructure has sufficient resources
If persistent, contact support with your run IDs.

​
Self-Hosting & Deployment

  • Python 3.11, 3.12, or 3.13
  • PostgreSQL database
  • An LLM API key (OpenAI, Anthropic, Azure, Gemini, or Ollama)
  • Docker (optional, for containerized deployment)
Run skyvern init for an interactive setup wizard. See the Quickstart for full instructions.
pip install --upgrade skyvern
alembic upgrade head  # Run database migrations
skyvern run server    # Restart the server
For Docker deployments, pull the latest image and restart your containers.
Set these environment variables:
ENABLE_OPENAI=true  # or ENABLE_ANTHROPIC, ENABLE_AZURE, etc.
OPENAI_API_KEY=sk-...
LLM_KEY=OPENAI_GPT4O
Skyvern supports OpenAI, Anthropic, Azure OpenAI, AWS Bedrock, Gemini, and Ollama. Run skyvern init llm for guided configuration.

​
Billing & Pricing

Pricing depends on your plan:
  • Pay-as-you-go — Charged per step or per task completion
  • Enterprise — Custom pricing based on volume
View your usage and billing at Settings > Billing.
Credits may be reserved for in-progress runs. Check:
  1. Active runs that haven’t completed yet
  2. Failed runs that consumed partial credit
  3. Pending charges that haven’t settled
Wait for active runs to complete, then check your balance again.
Go to Settings > Billing to download invoices. For custom invoice requirements (company name, VAT, etc.), contact support.

​
Still have questions?

Troubleshooting Guide

Step-by-step debugging for failed runs

Contact Support

Chat with us via the support widget