🔄 synced local 'docs/' with remote 'docs/'

docs/developers/credentials/troubleshooting-login.mdx

@@ -0,0 +1,349 @@
+---
+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>