> ## Documentation Index
> Fetch the complete documentation index at: https://runinfra.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Fix common issues with RunInfra pipeline building, optimization, deployment, and API integration, organized by category for fast diagnosis.

Most RunInfra problems fall into one of four categories: chat and pipeline building, optimization, deployment, or API integration. This page covers the most common issues in each area and tells you exactly what to do. If your situation isn't listed, check the support channels at the bottom.

## Chat and pipeline building

<AccordionGroup>
  <Accordion title="The agent keeps asking questions instead of building">
    The agent asks clarifying questions when your initial prompt is ambiguous. If the back-and-forth is slowing you down, tell it to proceed:

    ```text theme={"dark"}
    Just go with your best recommendation and we'll iterate from there.
    ```

    The agent will make opinionated choices and build the pipeline. You can always refine model selection, caching, and constraints in follow-up messages.
  </Accordion>

  <Accordion title="The agent picked the wrong model">
    Name the model you want explicitly:

    ```text theme={"dark"}
    Switch to Llama 3.1 8B.
    ```

    RunInfra supports a wide range of open-source LLMs. If you're unsure which model fits your use case, ask: "What model do you recommend for low-latency chat under \$200/month?"
  </Accordion>

  <Accordion title="I want to start over">
    Reset the current pipeline entirely:

    ```text theme={"dark"}
    Reset the pipeline and start from scratch.
    ```

    This clears the current configuration and conversation context. Your previous optimization results and deployment history are preserved in the dashboard.
  </Accordion>
</AccordionGroup>

## Optimization

<AccordionGroup>
  <Accordion title="Optimization is taking too long">
    Optimization typically completes in 2-5 minutes. The agent is profiling GPUs and running real inference benchmarks across model variants, so this is expected.

    If it appears stuck after 10 minutes, check in:

    ```text theme={"dark"}
    What's the status of the optimization?
    ```

    The agent will report progress or surface any errors it encountered.
  </Accordion>

  <Accordion title="Results don't meet my constraints">
    Optimization results reflect the constraints you gave the agent. If the results don't satisfy your latency, cost, or throughput targets, adjust the approach:

    ```text theme={"dark"}
    Optimize again with a smaller model.
    ```

    ```text theme={"dark"}
    Try a faster GPU.
    ```

    ```text theme={"dark"}
    Relax the latency constraint to 300ms.
    ```

    Each of these triggers a new optimization run with updated parameters. You can run multiple optimization sessions and compare results side by side in the dashboard.
  </Accordion>

  <Accordion title="I refreshed the page during an optimization run">
    Nothing is lost. The run executes server-side, so a refresh, a dropped connection, or a closed tab does not stop it. When you reopen the session, the dashboard re-attaches to the running execution within about a second: phases, live cost, and the Stop control resume updating.

    If a run was interrupted by a timeout, crash, or redeploy, it converges to a blocked state with retry actions instead of appearing to run forever. Use the resume or restart action to continue.

    Stopping a run cancels the underlying GPU work and its billing. A canceled run never promotes an optimization version; any candidate measured before the cancel keeps its measured results.
  </Accordion>

  <Accordion title="Quality evidence is weak or the optimized variant regressed">
    Aggressive low-bit quantization can reduce output quality on complex tasks. If the measured gate fails, stays pending, or your own test set looks worse, request a higher-precision variant:

    ```text theme={"dark"}
    Try FP8 where compatible, or fall back to FP16 for this model.
    ```

    FP8 can preserve more model fidelity than 4-bit quantization on compatible GPU/runtime pairs. Expect higher memory use or cost compared with low-bit variants.
  </Accordion>
</AccordionGroup>

## Deployment

<AccordionGroup>
  <Accordion title="Deployment failed">
    The agent shows error diagnostics inline when deployment fails. The most common causes are GPU availability and model size mismatches. Try:

    ```text theme={"dark"}
    Try a different GPU tier.
    ```

    ```text theme={"dark"}
    The model might be too large for this GPU. Recommend something bigger.
    ```

    If a specific GPU tier is temporarily unavailable in a region, switching tiers usually resolves the issue immediately.
  </Accordion>

  <Accordion title="The first request is slow (30-60 seconds)">
    This is normal behavior for the very first request after deployment. The model needs to load from storage and compile before it can serve inference. Subsequent requests are fast.

    <Note>
      RunInfra Cloud uses weight caching to keep cold starts under 2 seconds for all requests after the first. You don't need to configure anything to enable this.
    </Note>

    If you need zero cold start on every request, deploy in **Active** mode (available on a paid Core plan), which keeps the model resident on GPU at all times.
  </Accordion>

  <Accordion title="Endpoint returns 503">
    A 503 response means the endpoint is stopped or still provisioning. Two things to check:

    1. Open [Deployments](https://runinfra.ai/deployments) and verify the endpoint status.
    2. Ask the agent: "What's the status of my deployment?"

    If the endpoint is in **Stopped** state, start it from the Deployments dashboard or ask the agent to start it. If it's still provisioning, wait 1-3 minutes and retry.
  </Accordion>
</AccordionGroup>

## API integration

<AccordionGroup>
  <Accordion title="401 Unauthorized">
    Your API key is invalid, revoked, or not being sent correctly. Check all three:

    * The `Authorization` header is `Bearer YOUR_KEY` (no extra quotes or whitespace)
    * You are using a key from the same workspace as the target deployment
    * The key hasn't been revoked in [Settings > API Keys](https://runinfra.ai/settings/api-keys)

    Generate a new key if needed, key creation is instant and doesn't require redeployment.
  </Accordion>

  <Accordion title="403 Forbidden">
    Common causes: a pipeline-scoped key that doesn't match the pipeline id in the URL, or a plan-level limit was exceeded. Switch to a workspace-scoped key or regenerate a key tied to the correct pipeline. See [Authentication](/api-reference/authentication) for the two scopes.
  </Accordion>

  <Accordion title="429 Too Many Requests">
    You've exceeded the rate limit for your API key. The response includes a `Retry-After` header, wait that number of seconds before retrying.

    To increase the rate limit permanently, go to [Settings > API Keys](https://runinfra.ai/settings/api-keys) and update the limit for the key. Higher limits may require the Core or Enterprise plan.
  </Accordion>

  <Accordion title="403 with an upgrade prompt">
    You've hit a plan-level limit, for example running low on credits, or no paid plan yet. Add credits at [Settings > Cost](https://runinfra.ai/settings/cost#credits), or move to the Core plan at [Settings > Billing](https://runinfra.ai/settings/billing), to continue.
  </Accordion>
</AccordionGroup>

## Still stuck?

The right support channel depends on your plan:

| Plan           | Support channel                    |
| -------------- | ---------------------------------- |
| **Core**       | Priority email support             |
| **Enterprise** | Dedicated customer success manager |

You can also send feedback directly from within the app, or email support from your billing page.

## Related

<Columns cols={2}>
  <Card title="Debug the agent" icon="bug" href="/prompting/debugging">
    Redirect the agent when pipelines need course correction.
  </Card>

  <Card title="Monitor endpoints" icon="chart-line" href="/features/monitoring">
    Catch problems in the deployment metrics before they reach your users.
  </Card>

  <Card title="Deployment" icon="server" href="/deployments/overview">
    Flex, Active, scaling, and cold-start configuration.
  </Card>

  <Card title="FAQ" icon="message-circle-question" href="/faq/account">
    Answers to common questions about the platform.
  </Card>
</Columns>