> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sambanova.ai/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/v2.2.3/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/v2.2.3/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/v2.2.3/sambastack/service-administration/model-deployment/custom-resources/model-deployment" title="ModelDeployment">
    Full field reference for the deployment resource
  </Card>
</CardGroup>