kopia/kopia · error

entry not found

Error message

entry not found: %q

What it means

After a successful Child lookup, GetNestedEntry checks whether the returned entry is nil. Kopia's Directory.Child contract returns nil (not an error) when the named child does not exist, so this code converts that nil result into an explicit 'entry not found' error naming the missing component.

Solutions

1. Verify the exact path exists in the snapshot ('kopia ls <snapshotID>/path').
2. Check spelling and case of the path component.
3. List the parent directory to find the correct entry name.
4. Handle nil-entry semantics in calling code if you expect missing paths.

Example fix

// before
e, err := snapshotfs.FilesystemEntryFromIDWithPath(ctx, rep, sid+"/etc/passwd")
// after
if _, err := snapshotfs.FilesystemEntryFromIDWithPath(ctx, rep, sid+"/etc/passwd"); err != nil {
    // fall back or report missing path
    return handleMissing()
}

parent, err := snapshotfs.FilesystemEntryFromIDWithPath(ctx, rep, sid+"/etc")
if err != nil { return err }
dir, ok := parent.(fs.Directory)
if !ok { return errors.New("parent not a directory") }
if _, err := dir.Child(ctx, "passwd"); err != nil {
    return fmt.Errorf("entry missing in snapshot")
}

entry, err := snapshotfs.GetNestedEntry(ctx, root, parts)
if err != nil && strings.Contains(err.Error(), "entry not found") {
    return handleMissingPath(parts) // e.g. skip, list parent, or report
}

When it happens

Trigger: Calling GetNestedEntry / FilesystemEntryFromIDWithPath with a path whose final component does not exist in the parent directory — e.g. 'snapshotID/etc/passwd-does-not-exist'.

Common situations: Typos in restored file paths; paths referencing files deleted between snapshots; automation assuming a path exists in every snapshot; case-sensitivity mismatches.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• entry not found : parent is not a directory
• can't get local fs entry
• can't re-create top-level directory
• error resolving config file path
• failed to stat

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

Appendix: source

Thrown at snapshot/snapshotfs/objref.go:55

	current := startingDir

	for _, part := range pathElements {
		if part == "" {
			continue
		}

		dir, ok := current.(fs.Directory)
		if !ok {
			return nil, errors.Errorf("entry not found %q: parent is not a directory", part)
		}

		e, err := dir.Child(ctx, part)
		if err != nil {
			return nil, errors.Wrap(err, "error reading directory")
		}

		if e == nil {
			return nil, errors.Errorf("entry not found: %q", part)
		}

		current = e
	}

	return current, nil
}

func parseNestedObjectID(ctx context.Context, startingDir fs.Entry, parts []string) (object.ID, error) {
	e, err := GetNestedEntry(ctx, startingDir, parts)
	if err != nil {
		return object.EmptyID, err
	}

	hoid, ok := e.(object.HasObjectID)
	if !ok {
		return object.EmptyID, errors.New("entry without ObjectID")
	}

View on GitHub (pinned to 82495e54b5)