@@ -12,6 +12,8 @@ import (
 	"github.com/firecracker-microvm/firecracker-go-sdk"
 	openapiruntime "github.com/go-openapi/runtime"
 	"github.com/go-openapi/strfmt"
+	"go.opentelemetry.io/otel/attribute"
+	"go.opentelemetry.io/otel/metric"
 
 	"github.com/e2b-dev/infra/packages/orchestrator/pkg/sandbox/template"
 	"github.com/e2b-dev/infra/packages/orchestrator/pkg/sandbox/uffd/memory"
@@ -80,6 +82,10 @@ func (c *apiClient) loadSnapshot(
 
 	_, err := c.client.Operations.LoadSnapshot(&snapshotConfig)
 	if err != nil {
+		reason := classifySnapshotLoadFailure(err)
+		fcSnapshotLoadFailures.Add(ctx, 1, metric.WithAttributes(attribute.String("reason", string(reason))))
+		span.SetAttributes(attribute.String("snapshot_load.failure_reason", string(reason)))
+
 		return fmt.Errorf("error loading snapshot: %w", err)
 	}
 
 
@@ -59,6 +59,11 @@ var (
 	fcBlockFails         = utils.Must(telemetry.GetCounter(fcMeter, telemetry.SandboxFCBlockFails))
 	fcBlockNoAvailBuffer = utils.Must(telemetry.GetCounter(fcMeter, telemetry.SandboxFCBlockNoAvailBuffer))
 
+	// Refused snapshot loads, by reason. Recorded from the API error rather
+	// than from the metrics FIFO: a refused load stops the Firecracker process
+	// before it flushes, so its own metrics never carry the failure.
+	fcSnapshotLoadFailures = utils.Must(telemetry.GetCounter(fcMeter, telemetry.SandboxFCSnapshotLoadFailures))
+
 	// Block histograms.
 	fcBlockBytes                 = utils.Must(telemetry.GetHistogram(fcMeter, telemetry.SandboxFCBlockBytes))
 	fcBlockCount                 = utils.Must(telemetry.GetHistogram(fcMeter, telemetry.SandboxFCBlockCount))
 
@@ -0,0 +1,102 @@
+//go:build linux
+
+package fc
+
+import (
+	"context"
+	"errors"
+	"strings"
+
+	openapiruntime "github.com/go-openapi/runtime"
+
+	"github.com/e2b-dev/infra/packages/shared/pkg/fc/client/operations"
+	"github.com/e2b-dev/infra/packages/shared/pkg/fc/models"
+)
+
+// snapshotLoadFailureReason labels a refused snapshot load. It is deliberately
+// a small closed set: the fault text Firecracker returns is influenced by the
+// snapshot's own contents, so it is classified here and never emitted as a
+// metric attribute.
+type snapshotLoadFailureReason string
+
+const (
+	// snapshotLoadVcpuMSR is an MSR in the snapshot that the reading host's
+	// kernel will not accept — a kernel difference, not a CPU one. Every such
+	// host refuses the same snapshot, so its template is unusable, not slow.
+	snapshotLoadVcpuMSR snapshotLoadFailureReason = "vcpu_msr"
+	// snapshotLoadVcpuOther is any other vCPU restore failure.
+	snapshotLoadVcpuOther snapshotLoadFailureReason = "vcpu_other"
+	// snapshotLoadBadRequest is every other refusal, and the bucket a fault we
+	// have not classified lands in: Firecracker answered 400 and did not name
+	// the vCPUs. Memory backend, snapshot version and unreadable snapshot file
+	// all arrive here, as does a reworded fault from a future version.
+	snapshotLoadBadRequest snapshotLoadFailureReason = "bad_request"
+	// snapshotLoadUnavailable is a non-400 answer: the load never reached the
+	// snapshot.
+	snapshotLoadUnavailable snapshotLoadFailureReason = "unavailable"
+	// snapshotLoadTransport is the API socket being unreachable or answering
+	// unintelligibly, which says nothing about the snapshot.
+	snapshotLoadTransport snapshotLoadFailureReason = "transport"
+	// snapshotLoadTimeout is the load overrunning the request deadline.
+	// Firecracker never answered, but the sandbox never resumed either.
+	snapshotLoadTimeout snapshotLoadFailureReason = "timeout"
+	// snapshotLoadCanceled is the caller going away mid-load: not a broken
+	// snapshot, and the one reason an alert leaves out.
+	snapshotLoadCanceled snapshotLoadFailureReason = "canceled"
+)
+
+// classifySnapshotLoadFailure maps an error from Firecracker's PUT
+// /snapshot/load to the reason attribute. err must be non-nil.
+//
+// Firecracker's answer is read before the context: a refusal that lands as the
+// caller goes away is still a refusal.
+func classifySnapshotLoadFailure(err error) snapshotLoadFailureReason {
+	if badRequest, ok := errors.AsType[*operations.LoadSnapshotBadRequest](err); ok {
+		return classifySnapshotLoadFault(badRequest.GetPayload())
+	}
+
+	// Every other status arrives as the default response, including the 2xx
+	// codes go-swagger reports as errors because they are undeclared.
+	if _, ok := errors.AsType[*operations.LoadSnapshotDefault](err); ok {
+		return snapshotLoadUnavailable
+	}
+
+	if _, ok := errors.AsType[*openapiruntime.APIError](err); ok {
+		return snapshotLoadUnavailable
+	}
+
+	// No answer. The deadline is the orchestrator's own request timeout, so it
+	// expiring is an overrun load rather than a caller losing interest.
+	if errors.Is(err, context.DeadlineExceeded) {
+		return snapshotLoadTimeout
+	}
+
+	if errors.Is(err, context.Canceled) {
+		return snapshotLoadCanceled
+	}
+
+	return snapshotLoadTransport
+}
+
+// classifySnapshotLoadFault reads the fault text of a 400. An absent payload
+// is still a refusal, so it counts as one.
+func classifySnapshotLoadFault(payload *models.Error) snapshotLoadFailureReason {
+	if payload == nil {
+		return snapshotLoadBadRequest
+	}
+
+	// Firecracker nests the cause: "Failed to restore from snapshot: Failed to
+	// build microVM from snapshot: Failed to restore vCPUs: ... Failed to set
+	// all KVM MSRs for this vCPU." Match on the vCPU stage and then on the MSR
+	// step within it, so a vCPU failure for another reason is still separated
+	// from a memory-backend or version refusal.
+	if !strings.Contains(payload.FaultMessage, "Failed to restore vCPUs") {
+		return snapshotLoadBadRequest
+	}
+
+	if strings.Contains(payload.FaultMessage, "KVM MSRs") {
+		return snapshotLoadVcpuMSR
+	}
+
+	return snapshotLoadVcpuOther
+}
@@ -0,0 +1,98 @@
+//go:build linux
+
+package fc
+
+import (
+	"net"
+	"net/http"
+	"os"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"go.opentelemetry.io/otel"
+	"go.opentelemetry.io/otel/attribute"
+	sdkmetric "go.opentelemetry.io/otel/sdk/metric"
+	"go.opentelemetry.io/otel/sdk/metric/metricdata"
+
+	"github.com/e2b-dev/infra/packages/shared/pkg/telemetry"
+)
+
+type stubSnapfile string
+
+func (s stubSnapfile) Path() string { return string(s) }
+func (s stubSnapfile) Close() error { return nil }
+
+// The same refusal, as Firecracker words it, replayed by the stub.
+const msrFaultResponse = `{"fault_message":"Load snapshot error: Failed to restore from snapshot: Failed to build microVM from snapshot: Failed to restore vCPUs: Failed to run action on vcpu: Failed to set all KVM MSRs for this vCPU. Only a partial write was done."}`
+
+// The classifier is unit-tested on its own; this covers the wiring instead —
+// that a refusal on the real loadSnapshot path reaches the counter, under the
+// reason the fault deserves, with the attribute key an alert will group by. A
+// dropped Add or a renamed attribute is invisible in the classifier's tests
+// and would only show up as an alert that never fires.
+//
+//nolint:paralleltest // otel.SetMeterProvider mutates process state
+func TestLoadSnapshotRecordsRefusal(t *testing.T) {
+	reader := sdkmetric.NewManualReader()
+	otel.SetMeterProvider(sdkmetric.NewMeterProvider(sdkmetric.WithReader(reader)))
+
+	// Not t.TempDir(): its path embeds the full test name and overflows the
+	// 108-char unix sun_path limit.
+	dir, err := os.MkdirTemp("", "fc") //nolint:usetesting // t.TempDir embeds the test name and overflows the unix sun_path limit
+	require.NoError(t, err)
+	t.Cleanup(func() { _ = os.RemoveAll(dir) })
+
+	socket := dir + "/fc.sock"
+	listener, err := new(net.ListenConfig).Listen(t.Context(), "unix", socket)
+	require.NoError(t, err)
+
+	mux := http.NewServeMux()
+	mux.HandleFunc("PUT /snapshot/load", func(w http.ResponseWriter, _ *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(http.StatusBadRequest)
+		_, _ = w.Write([]byte(msrFaultResponse))
+	})
+	server := &http.Server{Handler: mux} //nolint:gosec // no timeouts needed for a stub on a private socket
+	go func() { _ = server.Serve(listener) }()
+	t.Cleanup(func() { _ = server.Close() })
+
+	// uffdReady is never closed: the load fails before it is waited on.
+	err = newApiClient(socket).loadSnapshot(t.Context(), dir+"/uffd.sock", make(chan struct{}), stubSnapfile(dir+"/snapfile"), false, false)
+	require.Error(t, err)
+
+	assert.Equal(t, int64(1), counterValue(t, reader, string(telemetry.SandboxFCSnapshotLoadFailures), "reason", string(snapshotLoadVcpuMSR)))
+}
+
+// counterValue sums the data points of one counter carrying the given
+// attribute, and fails when the counter was never recorded at all.
+func counterValue(t *testing.T, reader sdkmetric.Reader, name, attrKey, attrValue string) int64 {
+	t.Helper()
+
+	var collected metricdata.ResourceMetrics
+	require.NoError(t, reader.Collect(t.Context(), &collected))
+
+	for _, scope := range collected.ScopeMetrics {
+		for _, recorded := range scope.Metrics {
+			if recorded.Name != name {
+				continue
+			}
+
+			sum, ok := recorded.Data.(metricdata.Sum[int64])
+			require.Truef(t, ok, "%s is not an int64 sum: %T", name, recorded.Data)
+
+			var total int64
+			for _, point := range sum.DataPoints {
+				if value, found := point.Attributes.Value(attribute.Key(attrKey)); found && value.Emit() == attrValue {
+					total += point.Value
+				}
+			}
+
+			return total
+		}
+	}
+
+	t.Fatalf("%s was never recorded", name)
+
+	return 0
+}
@@ -0,0 +1,112 @@
+//go:build linux
+
+package fc
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"net"
+	"testing"
+
+	openapiruntime "github.com/go-openapi/runtime"
+	"github.com/stretchr/testify/assert"
+
+	"github.com/e2b-dev/infra/packages/shared/pkg/fc/client/operations"
+	"github.com/e2b-dev/infra/packages/shared/pkg/fc/models"
+)
+
+// Firecracker's fault for an MSR the reading host's kernel refuses. Kept whole,
+// as it arrives: the classifier matches two nested stages inside it.
+const msrFault = "Load snapshot error: Failed to restore from snapshot: Failed to build microVM from snapshot: Failed to restore vCPUs: Failed to run action on vcpu: Failed to set all KVM MSRs for this vCPU. Only a partial write was done."
+
+func badRequest(fault string) error {
+	return &operations.LoadSnapshotBadRequest{Payload: &models.Error{FaultMessage: fault}}
+}
+
+func TestClassifySnapshotLoadFailure(t *testing.T) {
+	t.Parallel()
+
+	for _, tc := range []struct {
+		name string
+		err  error
+		want snapshotLoadFailureReason
+	}{
+		{
+			name: "msr fault names the vcpu and the msr step",
+			err:  badRequest(msrFault),
+			want: snapshotLoadVcpuMSR,
+		},
+		{
+			// The reason exists so that an MSR alert does not absorb every
+			// other way vCPU restore can fail.
+			name: "vcpu restore failing elsewhere is not an msr failure",
+			err:  badRequest("Load snapshot error: Failed to restore from snapshot: Failed to build microVM from snapshot: Failed to restore vCPUs: Failed to run action on vcpu: Failed to set the TSC frequency."),
+			want: snapshotLoadVcpuOther,
+		},
+		{
+			name: "refusal that does not reach the vcpus",
+			err:  badRequest("Load snapshot error: Failed to restore from snapshot: Cannot deserialize the microVM state: Snapshot file was created by a different version"),
+			want: snapshotLoadBadRequest,
+		},
+		{
+			// A later Firecracker rewording the fault must still count as a
+			// refusal, so the total stays complete and only the breakdown
+			// loses precision.
+			name: "unrecognized fault text still counts as a refusal",
+			err:  badRequest("Load snapshot error: something we have never seen"),
+			want: snapshotLoadBadRequest,
+		},
+		{
+			name: "400 without a payload is still a refusal",
+			err:  &operations.LoadSnapshotBadRequest{},
+			want: snapshotLoadBadRequest,
+		},
+		{
+			name: "wrapped fault is classified through the wrapping",
+			err:  fmt.Errorf("error loading snapshot: %w", badRequest(msrFault)),
+			want: snapshotLoadVcpuMSR,
+		},
+		{
+			name: "non-400 status never reached the snapshot",
+			err:  operations.NewLoadSnapshotDefault(500),
+			want: snapshotLoadUnavailable,
+		},
+		{
+			name: "api error never reached the snapshot",
+			err:  openapiruntime.NewAPIError("load snapshot", nil, 503),
+			want: snapshotLoadUnavailable,
+		},
+		{
+			name: "unreachable socket says nothing about the snapshot",
+			err:  fmt.Errorf("post unix socket: %w", &net.OpError{Op: "dial", Err: errors.New("connection refused")}),
+			want: snapshotLoadTransport,
+		},
+		{
+			// The one reason an alert leaves out, so it must not absorb a load
+			// that never finished.
+			name: "caller cancellation is not a broken snapshot",
+			err:  fmt.Errorf("load snapshot: %w", context.Canceled),
+			want: snapshotLoadCanceled,
+		},
+		{
+			// The orchestrator's own request timeout: the load overran.
+			name: "deadline is a load that never finished",
+			err:  fmt.Errorf("load snapshot: %w", context.DeadlineExceeded),
+			want: snapshotLoadTimeout,
+		},
+		{
+			// Firecracker can answer while the caller is already gone. Reading
+			// the cancel instead would drop a dead template from the total.
+			name: "an answer outranks a cancel that arrived with it",
+			err:  fmt.Errorf("load snapshot: %w", errors.Join(badRequest(msrFault), context.Canceled)),
+			want: snapshotLoadVcpuMSR,
+		},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+
+			assert.Equal(t, tc.want, classifySnapshotLoadFailure(tc.err))
+		})
+	}
+}