kopia/kopia · error

unique ID not found

Error message

unique ID not found

What it means

parseUniqueID decodes a JSON document from a repository blob reader and extracts its UniqueID field. It throws this error when the JSON decodes successfully but the UniqueID field is empty, meaning the blob is not a valid unique-ID document that ensureRepositoriesHaveSameFormatBlob expects.

Solutions

1. Verify the format blob JSON in the repository actually contains a non-empty uniqueID field
2. Re-create or repair the repository format (kopia repository repair / restore from backup) if the blob is corrupted
3. Ensure both repositories being synced were created by a kopia version that writes unique IDs
4. If comparing repos intentionally, skip the sync for repos lacking unique IDs instead of running repository sync

Example fix

// before
type formatBlob struct {
    UniqueID string
}
// after - detect and surface the missing field
type formatBlob struct {
    UniqueID string `json:"uniqueID"`
}
if f.UniqueID == "" {
    return "", errors.Errorf("blob has no uniqueID (old format version?); upgrade the repository first")
}

var f struct{ UniqueID string `json:"uniqueID"` }
if err := json.NewDecoder(r.Reader()).Decode(&f); err != nil { return err }
if f.UniqueID == "" { return errors.New("blob JSON lacks uniqueID; upgrade repository format first") }

func hasUniqueID(f struct{ UniqueID string }) bool { return f.UniqueID != "" }

When it happens

Trigger: ensureRepositoriesHaveSameFormatBlob reads a blob whose JSON parses but has an empty or missing uniqueID field; e.g. comparing two repositories where one's format blob was written by a version that does not embed a unique ID.

Common situations: Upgrading an old kopia repository whose format-blob JSON predates the UniqueID field; pointing --repository-format at a foreign or hand-edited format file; corrupted or truncated format blob contents.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

• can't parse format blob
• can't retrieve sources
• epoch manager
• error computing repository token
• error connecting

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

Appendix: source

Thrown at cli/command_repository_sync.go:406

	if uniqueID1 == uniqueID2 {
		return nil
	}

	return errors.New("destination repository contains incompatible data")
}

func parseUniqueID(r gather.Bytes) (string, error) {
	var f struct {
		UniqueID string `json:"uniqueID"`
	}

	if err := json.NewDecoder(r.Reader()).Decode(&f); err != nil {
		return "", errors.Wrap(err, "invalid JSON")
	}

	if f.UniqueID == "" {
		return "", errors.New("unique ID not found")
	}

	return f.UniqueID, nil
}

View on GitHub (pinned to 82495e54b5)