AI inference troubleshooting

Errors by HTTP status code

Cold model timeouts

A model is “cold” when no orchestrator on the network has it loaded in GPU memory. The first request loads it, which takes 30 seconds to several minutes depending on model size. A cold model returns a 503 or a long pending response — it is not an error in your code. Mitigation strategies: Use warm models for latency-sensitive applications. The following models are warmed across the network:

Pipeline	Warm model
text-to-image	`SG161222/RealVisXL_V4.0_Lightning`
image-to-image	`timbrooks/instruct-pix2pix`
audio-to-text	`openai/whisper-large-v3`
image-to-text	`Salesforce/blip-image-captioning-large`
LLM	`meta-llama/Meta-Llama-3.1-8B-Instruct`

Implement retry with exponential backoff for any request that may target a cold model:

async function callWithRetry(fn: () => Promise<any>, maxRetries = 5): Promise<any> {
  let delay = 5000; // 5 seconds initial
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      return await fn();
    } catch (err: any) {
      if (err.statusCode === 503 && attempt < maxRetries) {
        await new Promise(r => setTimeout(r, delay));
        delay = Math.min(delay * 1.5, 60000); // cap at 60 seconds
      } else {
        throw err;
      }
    }
  }
}

Diagnosing a non-responsive job

When a request hangs with no response, check in this order:

Network connectivity — confirm you can reach livepeer.studio:

curl -I https://livepeer.studio/api/beta/generate/text-to-image
# Expect: HTTP/2 405 (not a 200 -- method not allowed on GET is correct)

Studio status — check https://status.livepeer.studio for active incidents.

Request construction — use curl to isolate from SDK behaviour:

curl -v -X POST https://livepeer.studio/api/beta/generate/text-to-image \
  -H "Authorization: Bearer $LIVEPEER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "test", "model_id": "SG161222/RealVisXL_V4.0_Lightning"}'

Model availability — some models are not always available on the network. Use a known warm model to confirm the integration works, then switch to your target model.
Gateway availability — if you are using a self-hosted or third-party gateway rather than livepeer.studio, confirm the gateway is running and accepting connections.

422 validation errors

A 422 response includes a body that identifies the failing field:

{
  "detail": [
    {
      "loc": ["body", "model_id"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

Common causes:

model_id is missing (required on all pipelines)
model_id format is wrong — must be a Hugging Face model ID string, e.g., SG161222/RealVisXL_V4.0_Lightning
Image input is sent as JSON instead of multipart/form-data (image-to-image, upscale, segment-anything-2)
Dimension values are not integers (use 1024, not "1024")

Getting help

If the above steps do not resolve the issue:

Discord: #builders and #ai-help channels in the Livepeer Discord. Include your request body (redact your API key), the response status, and the response body.
Forum: https://forum.livepeer.org — AI Research category for inference-specific questions.
GitHub: File an issue against livepeer/ai-runner for suspected network-level bugs.

AI Authentication

API key types, CORS configuration, and rotation.

Production Checklist

What to verify before shipping an AI application to production.

Start Here

Concepts

Get Started

Custom AI Workflows

Guides

Resources

AI inference troubleshooting

Errors by HTTP status code

Cold model timeouts

Diagnosing a non-responsive job

422 validation errors

Getting help

AI Authentication

Production Checklist

Start Here

Concepts

Get Started

Custom AI Workflows

Guides

Resources

​Errors by HTTP status code

​Cold model timeouts

​Diagnosing a non-responsive job

​422 validation errors

​Getting help

​Related pages

AI Authentication

Production Checklist

Errors by HTTP status code

Cold model timeouts

Diagnosing a non-responsive job

422 validation errors

Getting help

Related pages