Troubleshooting Login Failures

​

Common failure patterns

​

Credentials not entered

• Credential parameter not linked to workflow
• Wrong credential_id referenced
• Vault connection failed

1. Verify the credential exists:

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

2. Check workflow parameter configuration—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

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

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

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

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

• Push endpoint not forwarding codes
• totp_url returning errors
• totp_identifier mismatch between run and push

1. Verify your push endpoint — Check that it’s receiving and forwarding codes:

# 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:

# 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:

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:

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

​

Site-specific issues

​

CAPTCHA blocking login

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

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:

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 for enterprise CAPTCHA solutions

​

SSO/OAuth redirects

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:

# 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

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

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:

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
    """,
)

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

​

Debugging checklist

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

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

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

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

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

​

Error messages reference

​

Getting help

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)

​

Next steps