hashicorp/nomad · error

failed to compress snapshot file: %v

Error message

failed to compress snapshot file: %v

What it means

After writing the archive data, writeSnapshot closes the gzip.Writer to flush the final compressed stream. If closing the compressor fails (which surfaces any pending gzip checksum/write errors buffered in the stream), the snapshot is abandoned with this error.

Source

Thrown at helper/snapshot/snapshot.go:129

		if err := os.Remove(archive.Name()); err != nil {
			logger.Error("Failed to clean up temp snapshot", "error", err)
		}
	}()

	hash := sha256.New()
	out := io.MultiWriter(hash, archive)

	// Wrap the file writer in a gzip compressor.
	compressor := gzip.NewWriter(out)

	// Write the archive.
	if err := write(compressor, metadata, snap); err != nil {
		return nil, fmt.Errorf("failed to write snapshot file: %v", err)
	}

	// Finish the compressed stream.
	if err := compressor.Close(); err != nil {
		return nil, fmt.Errorf("failed to compress snapshot file: %v", err)
	}

	// Sync the compressed file and rewind it so it's ready to be streamed
	// out by the caller.
	if err := archive.Sync(); err != nil {
		return nil, fmt.Errorf("failed to sync snapshot: %v", err)
	}
	if _, err := archive.Seek(0, 0); err != nil {
		return nil, fmt.Errorf("failed to rewind snapshot: %v", err)
	}

	checksum := "sha-256=" + base64.StdEncoding.EncodeToString(hash.Sum(nil))

	keep = true
	return &Snapshot{archive, metadata.Index, checksum}, nil
}

// Index returns the index of the snapshot. This is safe to call on a nil

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Check disk space — the most common cause is ENOSPC on the final flush of the compressed stream.
2. Read the wrapped %v cause to identify the underlying write error (gzip will report checksum or writer errors).
3. If gzip reports checksum/corruption errors, ensure the archive data written by write() wasn't modified concurrently.
4. Retry snapshot creation once storage is healthy; a later successful New/NewFromFSM call is safe.

snap, err := snapshot.New(...)
if err != nil && strings.Contains(err.Error(), "failed to compress snapshot file") {
	if isTransient(err) { time.Sleep(backoff); return retry() }
	return err
}

When it happens

Trigger: New or NewFromFSM where compressor.Close() returns an error: typically an underlying write failure flushed during close (disk full, I/O error on the temp file), or the gzip stream already being in a bad state from an earlier write error.

Common situations: Disk ran out exactly at the point of flushing the gzip footer; the temp file's file descriptor hit an I/O error (e.g. ENOSPC, EIO) that only surfaces on the final flush/close.

Related errors

• failed to decompress snapshot: %v
• failed to read snapshot: %w
• failed to read snapshot: %w
• Failed to copy snapshot to temporary file: %v
• failed to finalize snapshot: %v

AI-assisted analysis of hashicorp/nomad@482b49bf1a (2026-09-04). Data as JSON: /api/errors/690db8ddfbb07fa7. Report an issue: GitHub.