Docs

Documentation

Debugging tips

Use ModelRiver's Observability tools to trace requests, inspect payloads, and identify the root cause of issues.

Systematic debugging approach

When diagnosing an issue, follow this sequence:

  1. Check Observability: Open Observability for the exact payload, provider sequence, and error details
  2. Inspect the timeline: The timeline view shows the complete request lifecycle, including failed provider attempts, webhook deliveries, and callbacks
  3. Verify provider quotas: Confirm provider-side quotas or rate limits haven't been reached
  4. Isolate the issue: Re-run the request with a known-good workflow to determine whether the issue is payload-related or system-wide
  5. Check customer data: Use cached data to trace which end user triggered the request

Using Observability for debugging

Request Logs

  • Filter by workflow, status, provider, or date range
  • Click into any request to see the full payload and response
  • Check meta.attempts to see if fallback providers were used

Timeline view

The timeline provides a chronological view of:

  • Provider selection and request dispatch
  • Fallback attempts with failure reasons
  • Webhook delivery attempts and responses
  • Event-driven callbacks with processing times

Payload inspection

  • Compare the sent payload against your expected schema
  • Verify messages array format matches provider expectations
  • Check that cache fields reference valid paths in your payload

Common debugging scenarios

AI returns unexpected format

  1. Check if a structured output is attached to the workflow
  2. Verify the schema matches your expectations
  3. Try a more capable model (e.g., upgrade from gpt-3.5 to gpt-4o)
  4. Review the raw provider response in Request Logs

Fallback provider keeps activating

  1. Check the timeline for the primary provider's failure reason
  2. Verify primary provider credentials are valid
  3. Monitor primary provider's status page for outages
  4. Consider adjusting timeout thresholds

Webhook not delivered

  1. Check the webhook delivery status in Request Logs
  2. Verify the endpoint URL is accessible and returns 2xx
  3. Check for signature verification failures in your server logs
  4. Review Delivery & retries for retry status

For comprehensive guidance on using request logs for debugging, see the Observability documentation.

Next steps