kopia/kopia · error

blob configuration

Error message

blob configuration

What it means

The `kopia maintenance set` command wraps errors from `rep.FormatManager().BlobCfgBlob(ctx)` with 'blob configuration'. This call reads the repository's blob-configuration blob (retention/epoch settings). Failure means the format manager could not load the blob configuration, so the command cannot validate whether the requested maintenance changes would extend retention.

Solutions

1. Confirm the repository opens correctly (`kopia repository status`) to rule out connection/credential issues.
2. Check that the format blob exists and is readable in the storage backend.
3. Upgrade or downgrade the CLI to the version that created the repository to avoid format incompatibility.
4. Inspect the wrapped cause via debug logging to pinpoint whether it is I/O, permissions, or parsing.

blobCfg, err := rep.FormatManager().BlobCfgBlob(ctx)
if err != nil {
    return fmt.Errorf("cannot validate retention, blob config unreadable: %w", err)
}

if err := maintenance.CheckExtendRetention(ctx, blobCfg, p); err != nil {
    return errors.Wrap(err, "proposed maintenance params rejected by retention policy")
}

When it happens

Trigger: Calling `kopia maintenance set` when the format blob containing blob configuration cannot be read or parsed: corrupted format blob, storage read failure, or repository connected with incompatible/insufficient access.

Common situations: Repositories migrated between storage backends where the format blob was not carried over, permission problems on the object store preventing reads of format metadata, or version skew where the blob config was written by a newer Kopia release.

Understand the failure class

Background: "missing required config value" errors: why libraries refuse to start when a configuration key is empty, unset, or blank — this error's family across 48 libraries.

Related errors

• error creating comparer
• maximum file size subject to compression
• minimum file size subject to compression
• unable to apply maintenance changes
• unable to create dir rewriter

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

Appendix: source

Thrown at cli/command_maintenance_set.go:198

		changedSchedule = true

		log(ctx).Infof("Quick maintenance paused until %v", formatTimestamp(s.NextQuickMaintenanceTime))
	}

	if pauseDuration := c.maintenanceSetPauseFull; pauseDuration != -1 {
		s.NextFullMaintenanceTime = rep.Time().Add(pauseDuration)
		changedSchedule = true

		log(ctx).Infof("Full maintenance paused until %v", formatTimestamp(s.NextFullMaintenanceTime))
	}

	if !changedParams && !changedSchedule {
		return errors.New("no changes specified")
	}

	blobCfg, err := rep.FormatManager().BlobCfgBlob(ctx)
	if err != nil {
		return errors.Wrap(err, "blob configuration")
	}

	if err = maintenance.CheckExtendRetention(ctx, blobCfg, p); err != nil {
		return errors.Wrap(err, "unable to apply maintenance changes")
	}

	if changedSchedule {
		if err := maintenance.SetSchedule(ctx, rep, s); err != nil {
			return errors.Wrap(err, "unable to set schedule")
		}
	}

	if changedParams {
		if err := maintenance.SetParams(ctx, rep, p); err != nil {
			return errors.Wrap(err, "unable to set params")
		}
	}

View on GitHub (pinned to 82495e54b5)