Skyvern/docs/developers/credentials/troubleshooting-login.mdx

---
title: Troubleshooting Login Failures
subtitle: Debug common authentication issues in your automations
description: Debug common login failures in Skyvern automations including credential errors, expired 2FA codes, CAPTCHA blocks, SSO redirects, and multi-step login flows. Includes a step-by-step debugging checklist.
slug: developers/credentials/troubleshooting-login
keywords:
  - login failure
  - debug
  - expired code
  - CAPTCHA block
  - SSO redirect
  - multi-step login
  - session timeout
  - checklist
  - recording
  - screenshot
---

Login failures are the most common issue in web automation. This guide covers the most frequent problems and how to resolve them.

---

## Common failure patterns

### Credentials not entered

**Symptoms:** Task completes but login never happened. The final screenshot shows the login page.

**Causes:**
- Credential parameter not linked to workflow
- Wrong `credential_id` referenced
- Vault connection failed

**Solutions:**

1. Verify the credential exists:

```bash
curl -X GET "https://api.skyvern.com/v1/credentials/cred_xyz789" \
  -H "x-api-key: $SKYVERN_API_KEY"
```

2. Check workflow parameter configuration to ensure the credential parameter is linked to a Login block

3. For vault integrations (Bitwarden, 1Password), verify connectivity:
   - Check vault credentials are valid
   - Ensure collection/vault IDs are correct
   - Test vault access independently

---

### Wrong credentials entered

**Symptoms:** Site shows "Invalid username or password" error.

**Causes:**
- Credentials stored incorrectly in your vault
- Site expects different format (email vs username)
- Password contains special characters causing issues

**Solutions:**

1. **Verify credentials work manually**: Log in to the site yourself with the same credentials

2. **Check username format**: Some sites require email, others want a username:
   ```
   ❌ john.smith
   ✓ john.smith@company.com
   ```

3. **Test credential retrieval**: Create a simple test task to verify Skyvern can access the credential

4. **Check for copy/paste errors**: Re-enter credentials in your vault, avoiding trailing spaces

---

### 2FA code expired

**Symptoms:** "Invalid code" or "Code expired" error after entering TOTP.

**Causes:**
- Clock drift between Skyvern and your authenticator
- Code fetched too early in the 30-second window
- Multi-field entry took too long

**Solutions:**

1. **Skyvern handles timing automatically**: If a TOTP code has less than 20 seconds remaining, Skyvern uses the next code

2. **For pushed codes**: Ensure your forwarding pipeline sends codes promptly. Delays over 30 seconds cause expiration.

3. **Check system clocks**: If self-hosting, ensure your server time is synchronized (NTP)

4. **Retry the run**: Intermittent timing issues often resolve on retry

---

### 2FA code never received

**Symptoms:** Task times out waiting for verification code.

**Causes:**
- Push endpoint not forwarding codes
- `totp_url` returning errors
- `totp_identifier` mismatch between run and push

**Solutions:**

1. **Verify your push endpoint**: Check that it's receiving and forwarding codes:

```bash
# Test your Zapier/webhook endpoint manually
curl -X POST "https://api.skyvern.com/v1/credentials/totp" \
  -H "x-api-key: $SKYVERN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "totp_identifier": "user@example.com",
    "content": "Your code is 123456",
    "source": "email"
  }'
```

2. **Check `totp_identifier` matches**: The identifier in your login must exactly match what you push:

```python
# These must match exactly
result = await client.login(
    credential_type="skyvern",
    credential_id="cred_xyz789",
    totp_identifier="user@example.com",  # ← This
    ...
)

await client.send_totp_code(
    totp_identifier="user@example.com",  # ← Must match this
    ...
)
```

3. **List recent codes** to verify they're being received:

```bash
curl -X GET "https://api.skyvern.com/v1/credentials/totp?totp_identifier=user@example.com" \
  -H "x-api-key: $SKYVERN_API_KEY"
```

4. **For pull-based 2FA**: Check your endpoint returns the correct format:

```json
{
  "task_id": "tsk_123456",
  "verification_code": "123456"
}
```

---

## Site-specific issues

### CAPTCHA blocking login

**Symptoms:** Login page shows CAPTCHA challenge that blocks automation.

**Solutions:**

1. **Use residential proxies**: Many CAPTCHAs trigger on datacenter IPs:

```python
result = await client.run_task(
    url="https://portal.example.com/login",
    prompt="Log in to the portal",
    proxy_location="RESIDENTIAL",
)
```

2. **Some CAPTCHAs can be solved**: Skyvern's AI can solve simple image-based challenges

3. **Browser profiles help**: Persistent browser state reduces CAPTCHA frequency:

```python
result = await client.login(
    credential_type="skyvern",
    url="https://portal.example.com/login",
    credential_id="cred_xyz789",
    browser_profile_id="bp_abc123",
)
```

4. **For persistent CAPTCHAs**: Contact [support@skyvern.com](mailto:support@skyvern.com) for enterprise CAPTCHA solutions

---

### SSO/OAuth redirects

**Symptoms:** Task fails when encountering "Sign in with Google/Microsoft" or similar SSO flows.

**Solutions:**

1. **Prefer direct credentials**: SSO flows involve multiple domains and are harder to automate. If possible, use direct username/password login.

2. **For required SSO**: Use browser sessions to maintain authentication state:

```python
# First run: Complete SSO manually or with Skyvern
result = await client.run_task(
    url="https://portal.example.com/login",
    prompt="Log in using Google SSO",
    browser_session_id="bs_xyz789",  # Persistent session
)

# Subsequent runs: Reuse the authenticated session
result = await client.run_task(
    url="https://portal.example.com/dashboard",
    prompt="Navigate to reports",
    browser_session_id="bs_xyz789",
)
```

3. **Check for direct login options**: Many sites offer traditional login alongside SSO (often under "Other login options")

---

### Multi-step login flows

**Symptoms:** Task enters username but fails to proceed to password page, or misses subsequent steps.

**Solutions:**

1. **Increase `max_steps`**: Multi-step logins require more navigation:

```python
result = await client.run_task(
    url="https://portal.example.com/login",
    prompt="Log in with my credentials",
    max_steps=15,  # Default is 10
)
```

2. **Use explicit prompts**: Guide Skyvern through the steps:

```python
result = await client.run_task(
    url="https://portal.example.com/login",
    prompt="""
    1. Enter the username and click Next
    2. Wait for the password page to load
    3. Enter the password and click Sign In
    4. If 2FA is required, enter the code
    """,
)
```

<Tip>
For login flows with credentials, use the `login()` method, which handles credential retrieval and 2FA automatically. Use `run_task()` only for general automation without credential management.
</Tip>

3. **Review recordings**: Watch the recording artifact to see exactly where the flow breaks

---

## Debugging checklist

Use this checklist to systematically debug login failures:

<Accordion title="Step-by-step debugging process">

**1. Check run status**

```bash
curl -X GET "https://api.skyvern.com/v1/runs/YOUR_RUN_ID" \
  -H "x-api-key: $SKYVERN_API_KEY"
```

Look at `status` and `failure_reason`.

**2. Review the recording**

Download the recording artifact and watch where the automation fails:

```bash
curl -X GET "https://api.skyvern.com/v1/runs/YOUR_RUN_ID/artifacts?artifact_type=recording" \
  -H "x-api-key: $SKYVERN_API_KEY"
```

**3. Check the final screenshot**

```bash
curl -X GET "https://api.skyvern.com/v1/runs/YOUR_RUN_ID/artifacts?artifact_type=screenshot_final" \
  -H "x-api-key: $SKYVERN_API_KEY"
```

**4. Verify credential access**

```bash
curl -X GET "https://api.skyvern.com/v1/credentials/YOUR_CREDENTIAL_ID" \
  -H "x-api-key: $SKYVERN_API_KEY"
```

**5. For 2FA issues, check code history**

```bash
curl -X GET "https://api.skyvern.com/v1/credentials/totp?totp_identifier=YOUR_IDENTIFIER" \
  -H "x-api-key: $SKYVERN_API_KEY"
```

**6. Review LLM reasoning**

Check `llm_request` and `llm_response` artifacts to understand what the AI was thinking.

</Accordion>

---

## Error messages reference

| Error | Meaning | Fix |
|-------|---------|-----|
| `FailedToGetTOTPVerificationCode` | HTTP request to `totp_url` failed | Check endpoint availability and response format |
| `NoTOTPVerificationCodeFound` | Polling timed out without receiving code | Ensure codes are pushed or endpoint returns codes |
| `TOTPExpiredError` | Code became invalid during entry | Usually auto-resolved on retry; check timing pipeline |
| `CredentialParameterNotFoundError` | Referenced credential parameter not found | Verify credential ID and parameter configuration |
| `CredentialParameterParsingError` | Failed to parse credential data | Check credential format matches expected schema |
| `CustomCredentialConfigurationError` | Custom vault service misconfigured | Verify API base URL and token are set correctly |

---

## Getting help

If you're stuck after trying the above solutions, contact Skyvern support with:

1. **Run ID**: The `run_id` from your failed run
2. **Recording**: Download and attach the recording artifact
3. **Description**: What you expected vs. what happened
4. **Target site**: The URL you're trying to automate (if not confidential)

Contact [support@skyvern.com](mailto:support@skyvern.com) or join our [Discord](https://discord.gg/skyvern) for community help.

---

## Next steps

<CardGroup cols={2}>
  <Card title="Store Credentials" icon="key" href="/developers/credentials/store-credentials">
    Review credential setup
  </Card>
  <Card title="Handle 2FA" icon="shield" href="/developers/credentials/handle-2fa">
    Configure two-factor authentication
  </Card>
</CardGroup>