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

# Troubleshooting deployments

Deployments fail in two places, and where a failure is reported tells you which table to read.

| Failure class                                                   | Raised by                                                                              | Applies to                                                                                                                            |
| --------------------------------------------------------------- | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| [Legalizer validation failures](#legalizer-validation-failures) | The legalizer, before any serving pod is created. Reported in `status.legalizerInfo`.  | A `ModelBundle` you authored, and any `ModelDeployment` that uses an inline `spec.models` specification, which is legalized in place. |
| [Deployment failures](#deployment-failures)                     | The operator, once it starts creating serving pods. Reported on the `ModelDeployment`. | Every deployment, whether it came from a bundle or from an inline specification.                                                      |

A deployment created from an inline `spec.models` specification is legalized in place, so both classes can apply to it.

## Legalizer validation failures

Errors appear in `status.legalizerInfo.errors` and cause `ValidationFailed`. Warnings appear in `status.legalizerInfo.warnings` and do not block deployment. See [Legalizer results](/docs/en/sambastack/service-administration/model-deployment/custom-resources/model-bundle#legalizer-results).

| Error Pattern                                                                | Cause                                                                                    | Resolution                                                                                                                  |
| ---------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `PEF pef1 and pef2 are not checkpoint compatible (checkpoint #0)`            | PEFs with the same `ckpt_sharing_uuid` cannot share checkpoint memory                    | Assign different `ckpt_sharing_uuid` values to the incompatible PEFs                                                        |
| `<checkpoint>: checkpoint sharing not enabled for <expert-a> and <expert-b>` | Warning only. The two experts cannot share checkpoint memory, so each holds its own copy | No action is required. To reclaim the duplicated memory, reduce the number of tiers or use PEFs that can share a checkpoint |
| `Bundle exceeds memory constraints`                                          | Combined PEF and checkpoint size exceeds RDU memory                                      | Reduce the number of tiers or batch sizes in the batching configuration                                                     |
| `PEF not found: <pef-name>`                                                  | Referenced PEF does not exist                                                            | Verify the PEF name with `kubectl get pefs`                                                                                 |
| Profile or model reference cannot be resolved                                | The named `ModelProfile` or `Model` does not exist in the namespace                      | Verify names with `kubectl get modelprofiles` and `kubectl get models`                                                      |

## Deployment failures

| Symptom                      | Possible Cause                                    | Resolution                                                                                   |
| ---------------------------- | ------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| Deployment stuck in pending  | Insufficient RDU resources                        | Check cluster capacity; reduce `minReplicas`                                                 |
| Checkpoint download fails    | Invalid checkpoint path or missing credentials    | Verify the `source` path in the Model; confirm the `sambanova-artifact-reader` secret exists |
| Model not accessible via API | Model name mismatch, or the model is not routable | Verify `spec.name` on the Model; confirm `modelSettings.routable` is not set to `false`      |
| Draft model served directly  | The draft model was left routable                 | Set `modelSettings.routable` to `false` on the draft model entry                             |

## Related documentation

<CardGroup cols={2}>
  <Card icon="cube" href="/docs/en/sambastack/service-administration/model-deployment/custom-resources/model-bundle" title="ModelBundle">
    Legalizer results and the fields the legalizer validates
  </Card>

  <Card icon="server" href="/docs/en/sambastack/service-administration/model-deployment/custom-resources/model-deployment" title="ModelDeployment">
    Full field reference for the deployment resource
  </Card>
</CardGroup>