Troubleshoot SambaStack Model Deployments - SambaNova Documentation

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	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	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.

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

ModelBundle

Legalizer results and the fields the legalizer validates

ModelDeployment

Full field reference for the deployment resource