Troubleshooting & FAQ

Common errors and solutions

Quick reference for common Runtype errors and how to resolve them.

Authentication errors

Error: Invalid API key

Message: 401 Unauthorized: Invalid or missing API key

Causes:

  • API key was revoked or expired
  • Typo in key
  • Using wrong key for environment

Solutions:

  1. Check Settings → Models or Integrations
  2. Regenerate key if expired
  3. Verify key matches environment (dev vs production)

Error: Domain not authorized

Message: 403 Forbidden: Domain not in allowed list

Causes:

  • Chat widget domain not added to allowed list

Solutions:

  1. Go to chat surface settings → Security
  2. Add current domain to allowed domains
  3. Save and retry

Flow execution errors

Error: Step timeout

Message: Execution timed out after 30s

Solutions:

  1. Increase Flow timeout in settings
  2. Optimize slow steps (use faster models)
  3. Add caching to avoid repeated API calls

Error: Undefined variable

Message: Cannot read property 'output' of undefined

Solutions:

  1. Check step name spelling
  2. Ensure step executes before being referenced
  3. Add conditional checks for optional variables

Error: Rate limit exceeded

Message: 429 Too Many Requests

Solutions:

  1. Switch to BYOK for dedicated rate limits
  2. Add delay steps between API calls
  3. Reduce batch concurrency

Flow validation errors

Error: Conditional nesting too deep

Message: Conditional steps may nest at most 10 levels deep.

Code: CONDITIONAL_NESTING_TOO_DEEP

Cause: A conditional step contains conditional steps nested more than 10 levels deep. This is rejected when you save or validate the flow.

Solutions:

  1. Flatten nested conditionals by combining conditions with && and || into a single conditional
  2. Use a transform-data step to evaluate the branching logic and return a result variable, then reference that variable in one conditional

Integration errors

Error: Slack message failed

Causes:

  • Channel deleted or archived
  • Bot removed from channel
  • Slack integration disconnected

Solutions:

  1. Verify channel exists and is active
  2. Re-invite Runtype bot to channel
  3. Reconnect Slack in Settings → Integrations

Error: Firecrawl scraping failed

Causes:

  • Website blocks automated access
  • Page requires authentication
  • Invalid URL

Solutions:

  1. Check URL is publicly accessible
  2. Use authentication parameters if available
  3. Try different wait_for selector

Model errors

Error: Model not available

Causes:

  • Model disabled in settings
  • Provider API key missing or invalid
  • Model deprecated by provider

Solutions:

  1. Enable model in Settings → Models
  2. Verify provider API key is current
  3. Switch to alternative model

Error: Context length exceeded

Message: Maximum context length exceeded

Solutions:

  1. Reduce prompt length
  2. Use model with larger context (e.g., Claude Sonnet 4.6 or Gemini 3.1 Pro)
  3. Summarize input before sending to AI

Surface errors

Error: Chat widget not appearing

Solutions:

  1. Check the script tag is placed before the closing </body> tag
  2. Verify surface status is Active
  3. Check browser console for errors
  4. Confirm domain is allowed

Error: API endpoint not found

Message: 404 Not Found

Solutions:

  1. Verify endpoint URL is correct
  2. Check Product ID and capability ID
  3. Ensure surface is active

For errors not listed here, check execution logs for detailed stack traces and error messages. Include execution ID when contacting support.

Next steps