kopia/kopia · critical

unable to prepare content preamble

Error message

unable to prepare content preamble

What it means

While building a new pending pack, the manager writes a random-length preamble of random bytes via writeRandomBytesToBuffer to make pack blob IDs/content harder to fingerprint. If that write fails the error is wrapped with 'unable to prepare content preamble'. The only failure mode is the underlying crypto/rand read failing inside writeRandomBytesToBuffer.

Solutions

1. Verify /dev/urandom availability and getrandom(2) support in the runtime environment.
2. Raise fd limits and check memory pressure.
3. Review container security profiles (seccomp/apparmor) for blocked randomness syscalls.
4. Restart the host/process; this failure does not recover mid-process.

Example fix

// before
err := bm.WriteContent(ctx, data) // fails with 'unable to prepare content preamble'
// after
if _, err := rand.Read(make([]byte, 8)); err != nil {
	log.Fatal("CSPRNG unavailable, aborting writes: ", err)
}
err := bm.WriteContent(ctx, data)

b := make([]byte, 8)
if _, err := cryptorand.Read(b); err != nil {
	return fmt.Errorf("CSPRNG unavailable: %w", err)
}

func csprngOK() bool {
	b := make([]byte, 4)
	_, err := cryptorand.Read(b)
	return err == nil
}

if err := bm.WriteContent(ctx, prefix, data); err != nil {
	if strings.Contains(err.Error(), "content preamble") {
		return fmt.Errorf("entropy failure on host %q: %w", hostname, err)
	}
	return err
}

When it happens

Trigger: Creating a new pending pack when the random byte generation fails — entropy source unavailable, fd exhaustion, or CSPRNG blocked by the sandbox.

Common situations: Same environment issues as crypto/rand failures: containers missing /dev/urandom, seccomp blocking getrandom, severe resource exhaustion.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

• can't get random bytes
• can't initialize randomness
• error generating salt
• error generating salt
• error getting random bytes

AI-assisted analysis of kopia/kopia@82495e54b5 (2026-09-07). Data as JSON: /api/errors/e24b8927453bcc57. Report an issue: GitHub.

Appendix: source

Thrown at repo/content/content_manager.go:775

	if err != nil {
		return nil, errors.Wrap(err, "unable to get session ID")
	}

	blobID := make([]byte, packBlobIDLength)
	if _, err := cryptorand.Read(blobID); err != nil {
		return nil, errors.Wrap(err, "unable to read crypto bytes")
	}

	suffix, berr := bm.format.RepositoryFormatBytes(ctx)
	if berr != nil {
		return nil, errors.Wrap(berr, "format bytes")
	}

	b.Append(suffix)

	//nolint:gosec
	if err := writeRandomBytesToBuffer(b, rand.Intn(bm.maxPreambleLength-bm.minPreambleLength+1)+bm.minPreambleLength); err != nil {
		return nil, errors.Wrap(err, "unable to prepare content preamble")
	}

	bm.pendingPacks[prefix] = &pendingPackInfo{
		prefix:           prefix,
		packBlobID:       blob.ID(fmt.Sprintf("%v%x-%v", prefix, blobID, sessionID)),
		currentPackItems: map[ID]Info{},
		currentPackData:  b,
	}

	return bm.pendingPacks[prefix], nil
}

// SupportsContentCompression returns true if content manager supports content-compression.
func (bm *WriteManager) SupportsContentCompression() bool {
	mp := bm.format.GetCachedMutableParameters()

	return mp.IndexVersion >= index.Version2
}

View on GitHub (pinned to 82495e54b5)