Dorod-Sky/docs/debugging/faq.mdx

---
title: Frequently Asked Questions
subtitle: Common questions and answers from the Skyvern community
slug: debugging/faq
---

## Troubleshooting

<Accordion title="Why did my task fail or terminate?">
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](/debugging/troubleshooting-guide) for detailed steps.
</Accordion>

<Accordion title="Why is the AI clicking the wrong element?">
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.
</Accordion>

<Accordion title="Why is my task timing out?">
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
</Accordion>

<Accordion title="Why can't Skyvern find an element on the page?">
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
</Accordion>

<Accordion title="Why is the extracted data wrong or incomplete?">
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"
</Accordion>

---

## Workflows

<Accordion title="How do I pass parameters to a workflow?">
Define parameters in the workflow editor, then pass them when starting a run:

```python
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](/workflows/workflow-parameters) for details.
</Accordion>

<Accordion title="How do I use credentials in a workflow?">
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](/sdk-reference/credentials) for setup instructions.
</Accordion>

<Accordion title="Can I run workflows on a schedule?">
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](/running-tasks/webhooks-faq) to get notified when scheduled runs complete.
</Accordion>

<Accordion title="Why isn't my workflow using the parameter values I passed?">
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
</Accordion>

<Accordion title="How do I run workflows sequentially with the same credentials?">
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.
</Accordion>

---

## Configuration

<Accordion title="Where do I find my API key?">
Go to [Settings](https://app.skyvern.com/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.
</Accordion>

<Accordion title="How do I change the LLM model?">
**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
</Accordion>

<Accordion title="How do I configure proxy settings?">
Set `proxy_location` when running a task:

```python
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.
</Accordion>

<Accordion title="Can I increase the max steps limit beyond 75?">
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.
</Accordion>

---

## API & Integration

<Accordion title="How do I poll for task completion?">
Check the run status in a loop:

```python
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](/running-tasks/webhooks-faq) to get notified when runs complete without polling.
</Accordion>

<Accordion title="Where can I find extracted data after a run completes?">
The extracted data is in `run.output`:

```python
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.
</Accordion>

<Accordion title="How do I get the recording URL from the API?">
The recording URL is included in the run response:

```python
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.
</Accordion>

<Accordion title="How do I trigger a workflow via API?">
Use the `run_workflow` method:

```python
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.
</Accordion>

---

## Authentication & Credentials

<Accordion title="Why is my login failing?">
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.
</Accordion>

<Accordion title="How do I handle CAPTCHA?">
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.
</Accordion>

<Accordion title="How do I set up 2FA/TOTP?">
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](/credentials/totp) for detailed instructions.
</Accordion>

<Accordion title="How do I handle email OTP verification?">
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.
</Accordion>

---

## Browser & Proxy

<Accordion title="Why is the site blocking Skyvern?">
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
</Accordion>

<Accordion title="How do I persist cookies across runs?">
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.
</Accordion>

<Accordion title="Can I connect Skyvern to my local browser?">
Yes, for self-hosted installations:

```bash
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.
</Accordion>

<Accordion title="Why am I getting a 504 timeout when creating browser sessions?">
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.
</Accordion>

---

## Self-Hosting & Deployment

<Accordion title="What are the requirements for self-hosting Skyvern?">
- 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](/getting-started/quickstart) for full instructions.
</Accordion>

<Accordion title="How do I update my self-hosted Skyvern instance?">
```bash
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.
</Accordion>

<Accordion title="How do I configure a custom LLM provider?">
Set these environment variables:

```bash
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.
</Accordion>

---

## Billing & Pricing

<Accordion title="How is pricing calculated?">
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](https://app.skyvern.com/billing).
</Accordion>

<Accordion title="Why does it say insufficient balance when I have credit?">
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.
</Accordion>

<Accordion title="How do I get invoices for my payments?">
Go to [Settings > Billing](https://app.skyvern.com/billing) to download invoices. For custom invoice requirements (company name, VAT, etc.), contact support.
</Accordion>

---

## Still have questions?

<CardGroup cols={2}>
  <Card
    title="Troubleshooting Guide"
    icon="wrench"
    href="/debugging/troubleshooting-guide"
  >
    Step-by-step debugging for failed runs
  </Card>
  <Card
    title="Contact Support"
    icon="headset"
    href="https://app.skyvern.com"
  >
    Chat with us via the support widget
  </Card>
</CardGroup>