kopia/kopia · error

error writing dir manifest

Error message

error writing dir manifest

What it means

During a checkpointed directory upload, the intermediate checkpoint manifest is persisted with snapshotfs.WriteDirManifest, which writes the directory manifest object to the repository. Failure to write that manifest (storage error, metadata serialization failure) aborts with this error.

Solutions

1. Check the wrapped cause: verify repository storage is reachable and writable
2. Retry the snapshot once storage is healthy
3. Run kopia repository status / verify storage-backend health
4. Disable checkpointing if the checkpoint write path is repeatedly failing

if _, err := repo.VerifyObject(ctx, oid); err != nil {
    return fmt.Errorf("repository not writable/healthy: %v", err)
}

de, err := uploadDirInternal(...)
if err != nil && strings.Contains(err.Error(), "error writing dir manifest") {
    if isTransient(err) {
        return retryWithBackoff(func() error { _, err = uploadDirInternal(...); return err })
    }
    return err
}

When it happens

Trigger: Thrown at snapshot/upload/upload.go:1192 when the library encounters an invalid state.

Common situations: Storage backend outages or quota exhaustion during long uploads; repository object-write failures; encryption/format errors on metadata objects.

Understand the failure class

Background: "failed to write file", "Could not save figure", "Error saving remote file" — file write failed: causes and fixes across languages and libraries — this error's family across 38 libraries.

Related errors

• checkpoint interval cannot be greater than
• error checkpointing children
• error writing dir manifest
• error deleting
• error executing before-folder action

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

Appendix: source

Thrown at snapshot/upload/upload.go:1192

	childCheckpointRegistry := &checkpointRegistry{}

	metadataComp := policyTree.EffectivePolicy().MetadataCompressionPolicy.MetadataCompressor()

	thisCheckpointRegistry.addCheckpointCallback(directory.Name(), func() (*snapshot.DirEntry, error) {
		// when snapshotting the parent, snapshot all our children and tell them to populate
		// childCheckpointBuilder
		thisCheckpointBuilder := thisDirBuilder.Clone()

		// invoke all child checkpoints which will populate thisCheckpointBuilder.
		if err := childCheckpointRegistry.runCheckpoints(thisCheckpointBuilder); err != nil {
			return nil, errors.Wrapf(err, "error checkpointing children")
		}

		checkpointManifest := thisCheckpointBuilder.Build(fs.UTCTimestampFromTime(directory.ModTime()), IncompleteReasonCheckpoint)

		oid, err := snapshotfs.WriteDirManifest(ctx, u.repo, dirRelativePath, checkpointManifest, metadataComp)
		if err != nil {
			return nil, errors.Wrap(err, "error writing dir manifest")
		}

		return newDirEntryWithSummary(directory, oid, checkpointManifest.Summary)
	})
	defer thisCheckpointRegistry.removeCheckpointCallback(directory.Name())

	if err := u.processChildren(ctx, childCheckpointRegistry, thisDirBuilder, localDirPathOrEmpty, dirRelativePath, directory, policyTree, uniqueDirectories(previousDirs)); err != nil && !errors.Is(err, errCanceled) {
		return nil, err
	}

	dirManifest := thisDirBuilder.Build(fs.UTCTimestampFromTime(directory.ModTime()), u.incompleteReason())

	oid, err := snapshotfs.WriteDirManifest(ctx, u.repo, dirRelativePath, dirManifest, metadataComp)
	if err != nil {
		return nil, errors.Wrapf(err, "error writing dir manifest: %v", directory.Name())
	}

	return newDirEntryWithSummary(directory, oid, dirManifest.Summary)

View on GitHub (pinned to 82495e54b5)