Skip to main content
This guide provides quick solutions to the most frequently encountered issues when using Skyvern.

​
Task execution issues

Symptom: Status is timed_out, task exceeded max_steps limit.Common causes:
  • Task is too complex for the default step limit
  • AI got stuck in a navigation loop
  • Missing completion criteria causes infinite attempts
Solutions:
  • Increase max_steps in your task parameters (default: 50, max: 75)
  • Add explicit completion criteria: “COMPLETE when you see ‘Order confirmed’”
  • Break complex tasks into multiple workflow blocks
  • Check the recording to see where it got stuck
Symptom: Status is completed, but extracted data is incorrect or incomplete.Diagnostic steps:
  1. Check screenshot_final — Did it end on the right page?
  2. Check llm_response_parsed — Did it target the right elements?
Solutions:
  • Add specific descriptions in your schema: "description": "The price in USD, without currency symbol"
  • Add visual hints in your prompt: “The price is displayed in bold below the product title”
  • Make schema fields optional where data might not always be present
  • Add validation: “Only extract data visibly displayed on the page. Return null if not found”
Symptom: Run stays in queued status and never starts.Likely causes:
  • Concurrency limit reached for your account
  • Sequential run lock active (another run with same credential)
  • High platform load
Solutions:
  • Wait for other runs to complete
  • Check your plan’s concurrency limits in Settings
  • If using “Run Sequentially” with credentials, ensure prior runs finish
  • Contact support if issue persists
Symptom: Getting 504 Gateway Timeout errors when creating browser sessions.Solutions:
  • Retry after a few seconds — usually transient
  • For self-hosted: check infrastructure resources (memory, CPU)
  • If persistent, contact support with your run IDs

​
Element interaction issues

Symptom: Recording shows AI clicking something other than intended.Diagnostic steps:
  1. Check visible_elements_tree — Was the element detected?
  2. Check llm_prompt — Was the target described clearly?
Solutions:
  • Add distinguishing details: “Click the blue Submit button at the bottom of the form”
  • Reference surrounding text: “Click Download in the row that says ‘January 2024’”
  • Be specific about position: “Click the first result” or “Click the link in the header”
  • Add visual context about nearby elements
Symptom: failure_reason mentions element couldn’t be found.Common causes:
  • Element loads dynamically after page appears
  • Element is inside an iframe
  • Element requires scrolling to become visible
  • Element uses unusual rendering (canvas, shadow DOM)
Solutions:
  • Add max_screenshot_scrolls to capture lazy-loaded content
  • Describe elements visually rather than by technical properties
  • Add explicit wait instructions: “Wait 3 seconds for the page to fully load”
  • Add scroll instructions: “Scroll down to find the element”
Symptom: Dates entered in wrong format (MM/DD vs DD/MM) or wrong date entirely.Solutions:
  • Specify exact format: “Enter the date as 15/01/2024 (DD/MM/YYYY format)”
  • For date pickers: “Click the date field, then select January 15, 2024 from the calendar”
  • If site auto-formats: “Type 01152024 and let the field format it”
  • Provide the exact date string to enter
Symptom: AI keeps cycling through address suggestions or selects wrong address.Solutions:
  • Specify selection: “Type ‘123 Main St’ and select the first suggestion showing ‘New York, NY’”
  • Disable autocomplete: “Type the full address without using autocomplete suggestions”
  • Break into steps: “Enter street address, wait for dropdown, select the matching suggestion”
  • Add wait time after typing

​
Authentication issues

Symptom: Status is terminated with login-related failure reason.Diagnostic steps:
  1. Check screenshot_final — Is there an error message?
  2. Watch the recording — Were fields filled correctly?
Common causes:
  • Expired or incorrect credentials
  • CAPTCHA appeared
  • MFA/2FA required but not configured
  • Site detected automation
Solutions:
  • Verify credentials in your credential store
  • Use RESIDENTIAL_ISP proxy for more trusted IPs
  • Configure TOTP if MFA is required
  • Use a browser profile with an existing authenticated session
Symptom: failure_reason mentions CAPTCHA.Solutions (in order of preference):
  1. Browser profile — Use 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 that require human intervention.
Symptom: Login fails at 2FA step.Solutions:
  1. TOTP (Time-based One-Time Password):
    • Go to Settings > Credentials
    • Create a new TOTP credential with your authenticator secret
    • Reference the TOTP credential in your workflow’s login block
  2. Email OTP:
    • Set up an email listener (Zapier, custom webhook, etc.)
    • Use a Human Interaction block to wait for the code
    • Send the code back to Skyvern via API
  3. SMS OTP:
    • Similar to email OTP, use external integration
    • Consider if the site supports TOTP as an alternative

​
Browser and proxy issues

Symptom: Site shows anti-bot page or blocks access.Common causes:
  • IP reputation (datacenter IPs often blocked)
  • Browser fingerprinting detection
  • Rate limiting
Solutions:
  • Use RESIDENTIAL_ISP proxy for consistent, trusted IPs
  • Create a browser profile with an existing authenticated session
  • Slow down requests by adding explicit waits
  • Avoid rapid repeated requests to the same endpoint
Symptom: Site displays in unexpected language based on proxy location.Solutions:
  • Use appropriate proxy: RESIDENTIAL_US for English US sites
  • Add instruction: “If the site asks for language preference, select English”
  • Set language in URL if supported: https://example.com/en/
  • Use browser profile with language preference set
Symptom: Login state is lost between runs.Solution: 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.

​
Data extraction issues

Symptom: Extracted data contains information not visible on the page.Diagnostic steps:
  1. Check screenshot_final — Is the data actually visible?
  2. Check llm_response_parsed — What did the AI claim to see?
Solutions:
  • Add instruction: “Only extract data visibly displayed on the page. Return null if not found”
  • Make schema fields optional where appropriate
  • Add validation rules in your schema descriptions
  • Be explicit: “If price is not displayed, set price to null instead of guessing”
Symptom: Files download repeatedly, wrong files, or downloads don’t complete.Diagnostic steps:
  1. Watch the recording — Was the download button clicked correctly?
  2. Check downloaded_files in the response
Solutions:
  • Be specific: “Click the PDF download button, not the Excel one”
  • Add wait time: “Wait 5 seconds for the download to complete”
  • For multi-step downloads: “Click Download, then select PDF format, then click Confirm”
  • Check if download requires authentication or cookies
Symptom: Data type doesn’t match schema or is formatted incorrectly.Solutions:
  • Add format specification in description: "description": "Price as a number without currency symbol"
  • Specify units: "description": "Weight in pounds (numeric value only)"
  • Add examples in description: "description": "Date in YYYY-MM-DD format, e.g., 2024-01-15"
  • Use proper JSON schema types (string, number, boolean, array, object)

​
Workflow issues

Symptom: Recording shows AI repeating the same actions without progressing.Diagnostic steps:
  1. Watch the recording — What pattern is repeating?
  2. Check conditional block exit conditions
Solutions:
  • Add termination instruction: “STOP if you’ve attempted this action 3 times without success”
  • Add completion markers: “COMPLETE when you see ‘Success’ message”
  • Review loop conditions — ensure exit criteria are achievable
  • Add explicit step limits
Symptom: Workflow doesn’t use the parameter values passed.Common causes:
  • Incorrect parameter placeholder syntax
  • Parameter name mismatch (case-sensitive)
  • Parameter not defined in workflow
  • Parameter passed after run started
Solutions:
  • Use correct syntax: {{ parameter_name }} (NOT {parameter_name} or $parameter_name)
  • Verify parameter name matches exactly (case-sensitive)
  • Ensure parameter is defined in the workflow’s parameter list
  • Pass parameters when starting the run, not after
Symptom: Login block fails despite valid credentials.Solutions:
  1. Verify credentials in Settings > Credentials
  2. Check credential is selected in the Login block’s dropdown
  3. Ensure credential type matches (username/password vs TOTP)
  4. Test credentials manually to verify they work
  5. Check if site requires additional verification

​
Self-hosting issues

Symptom: Skyvern server won’t start, database connection errors.Solutions:
  • Verify PostgreSQL is running
  • Check connection string format: postgresql+psycopg://user:password@localhost:5432/skyvern
  • Ensure database exists: createdb skyvern
  • Run migrations: alembic upgrade head
  • Check firewall/network access to database
Symptom: Tasks fail immediately with browser launch errors.Solutions:
  • Ensure Playwright browsers are installed: playwright install chromium
  • Check Chrome/Chromium path in environment variables
  • Verify sufficient disk space and memory
  • For Docker: ensure container has proper permissions
  • Check logs for specific error messages
Symptom: Tasks fail with LLM-related errors.Solutions:
  • Verify API key is valid and has credits
  • Check LLM_KEY environment variable is set correctly
  • Ensure ENABLE_OPENAI (or appropriate provider) is true
  • Check API rate limits
  • Verify network access to LLM provider API

​
Still having issues?

Error Handling

Understanding and handling errors

View Artifacts

Learn how to inspect recordings and logs

FAQ

Frequently asked questions

Get Support

Join our Discord community

Build docs developers (and LLMs) love

Get started for freeTalk to us