Skip to main content
When a run fails or produces unexpected results, this guide helps you identify the cause and fix it.

Quick debugging checklist

Skyvern Debugging Checklist
1

Check run status

Call get_run(run_id) and check status and failure_reason
2

Find the failed step

Call get_run_timeline(run_id) to see which block failed
3

Inspect artifacts

Check screenshot_final to see where it stopped, recording to watch what happened
4

Determine the fix

Adjust prompt, parameters, or file a bug based on what you find
Key artifacts to check:
  • screenshot_final — Final page state
  • recording — Video of what happened
  • llm_response_parsed — What the AI decided to do
  • visible_elements_tree — What elements were detected
  • har — Network requests if something failed to load

Step 1: Check the run

import os
from skyvern import Skyvern

client = Skyvern(api_key=os.getenv("SKYVERN_API_KEY"))

run = await client.get_run(run_id)

print(f"Status: {run.status}")
print(f"Failure reason: {run.failure_reason}")
print(f"Step count: {run.step_count}")
print(f"Output: {run.output}")
StatusWhat it meansLikely cause
completedRun finished, but output may be wrongPrompt interpretation issue
failedSystem errorBrowser crash, network failure
terminatedAI gave upLogin blocked, CAPTCHA, page unavailable
timed_outExceeded max_stepsTask too complex, or AI got stuck
canceledManually stopped

Step 2: Read the step timeline

The timeline shows each block and action in execution order.
timeline = await client.get_run_timeline(run_id)

for item in timeline:
    if item.type == "block":
        block = item.block
        print(f"Block: {block.label}")
        print(f"  Status: {block.status}")
        print(f"  Duration: {block.duration}s")
        if block.failure_reason:
            print(f"  Failure: {block.failure_reason}")
        for action in block.actions:
            print(f"  Action: {action.action_type} -> {action.status}")

Step 3: Inspect artifacts

artifacts = await client.get_run_artifacts(
    run_id,
    artifact_type=["screenshot_final", "llm_response_parsed", "skyvern_log"]
)

for a in artifacts:
    print(f"{a.artifact_type}: {a.signed_url}")
See Using Artifacts for the full list of artifact types.

Common issues and fixes

Run Status Issues

Symptom: Status is completed, but the extracted data is incorrect or incomplete.Check: screenshot_final (right page?) and llm_response_parsed (right elements?)Fix:
  • Add specific descriptions in your schema: "description": "The price in USD, without currency symbol"
  • Add visual hints: “The price is displayed in bold below the product title”
Symptom: Status is timed_out.Check: recording (stuck in a loop?) and step_count (how many steps?)Fix:
  • Increase max_steps if the task genuinely needs more steps
  • Add explicit completion criteria: “COMPLETE when you see ‘Order confirmed’”
  • Break complex tasks into multiple workflow blocks
Symptom: Run stays in queued status and never starts.Likely causes: Concurrency limit hit, sequential run lock, or high platform load.Fix:
  • Wait for other runs to complete
  • Check your plan’s concurrency limits in Settings
  • If using “Run Sequentially” with credentials, ensure prior runs finish
Symptom: Getting 504 Gateway Timeout errors when creating browser sessions.Fix:
  • Retry after a few seconds — usually transient
  • For self-hosted: check infrastructure resources
  • If persistent, contact support with your run IDs

Element & Interaction Issues

Symptom: Recording shows the AI clicking something other than intended.Check: visible_elements_tree (element detected?) and llm_prompt (target described clearly?)Fix:
  • 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’”
Symptom: failure_reason mentions an element couldn’t be found.Check: screenshot_final (element visible?) and visible_elements_tree (element detected?)Likely causes: Dynamic loading, iframe, below the fold, unusual rendering (canvas, shadow DOM)Fix:
  • Add max_screenshot_scrolls to capture lazy-loaded content
  • Describe elements visually rather than by technical properties
  • Add wait or scroll instructions in your prompt
Symptom: Dates entered in wrong format (MM/DD vs DD/MM) or wrong date entirely.Check: recording (how did AI interact with the date picker?)Fix:
  • 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”
Symptom: AI keeps clicking through address suggestions in a loop, or selects wrong address.Check: recording (is autocomplete dropdown appearing?)Fix:
  • 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”

Authentication Issues

Symptom: Status is terminated with login-related failure reason.Check: screenshot_final (error message?) and recording (fields filled correctly?)Likely causes: Expired credentials, CAPTCHA, MFA required, automation detectedFix:
  • Verify credentials in your credential store
  • Use RESIDENTIAL_ISP proxy for more stable IPs
  • Configure TOTP if MFA is required
  • Use a browser profile with an existing session
Symptom: failure_reason mentions CAPTCHA.Fix options:
  1. Browser profile — Use an authenticated session that skips login
  2. Human interaction block — Pause for manual CAPTCHA solving
  3. Different proxy — Use RESIDENTIAL_ISP for static IPs sites trust more

Data & Output Issues

Symptom: Extracted data contains information not on the page.Check: screenshot_final (data visible?) and llm_response_parsed (what did AI claim to see?)Fix:
  • Add instruction: “Only extract data visibly displayed on the page. Return null if not found”
  • Make schema fields optional where appropriate
  • Add validation: “If price is not displayed, set price to null instead of guessing”
Symptom: Files download repeatedly, wrong files, or downloads don’t complete.Check: recording (download button clicked correctly?) and downloaded_files in responseFix:
  • Be specific: “Click the PDF download button, not the Excel one”
  • Add wait time: “Wait for the download to complete”
  • For multi-step downloads: “Click Download, then select PDF format, then click Confirm”

Environment Issues

Symptom: Site displays in unexpected language based on proxy location.Check: What proxy_location is being used? Does site geo-target?Fix:
  • Use appropriate proxy: RESIDENTIAL_US for English US sites
  • Add instruction: “If the site asks for language preference, select English”
  • Set language in URL: https://example.com/en/
Symptom: Recording shows AI repeating the same actions without progressing.Check: recording (what pattern is repeating?) and conditional block exit conditionsFix:
  • Add termination: “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

When to adjust prompts vs parameters

Adjust prompt

  • AI misunderstood what to do
  • Clicked wrong element
  • Ambiguous completion criteria
  • Extracted wrong data

Adjust parameters

  • Timed out → increase max_steps
  • Site blocked → change proxy_location
  • Content didn’t load → increase max_screenshot_scrolls

File a bug

  • Visible element not detected
  • Standard UI patterns don’t work
  • Consistent wrong element despite clear prompts

Next steps

Using Artifacts

Detailed reference for all artifact types

Reliability Tips

Write prompts that fail less often