dagger/dagger · error

get canonical checkout snapshot

Error message

get canonical checkout snapshot: %w

What it means

This error wraps any failure that occurs while evaluating the canonical checkout snapshot (the underlying cache ref) of the Directory passed to MaterializeGitUncommittedPack. Dagger needs the parent snapshot before it can create a new cache ref to apply uncommitted changes on top of; if resolving/evaluating that snapshot fails, the error is wrapped with this message. It indicates the source Directory tree could not be materialized, often due to an upstream error in the tree's evaluation chain.

Solutions

  1. Inspect the wrapped (%w) cause in the error chain — it names the real failure in the snapshot evaluation
  2. Re-run the command; transient mount/cache evaluation failures often resolve on retry
  3. Restart the Dagger engine to clear corrupted cache state (dagger engine restart / prune cache)
  4. Verify the source directory tree is valid and its own dependencies (services, git ref) resolve correctly before calling

Example fix

// before: no context on failure path
parent, err := tree.Self().Snapshot.GetOrEval(ctx, tree.Result)
if err != nil {
    return inst, err
}
// after: wrap with actionable message
parent, err := tree.Self().Snapshot.GetOrEval(ctx, tree.Result)
if err != nil {
    return inst, fmt.Errorf("get canonical checkout snapshot: %w", err)
}
Defensive patterns

Strategy: try-catch

Validate before calling

// ensure source dir resolves before materializing
if _, err := tree.Self().Snapshot.GetOrEval(ctx, tree.Result); err != nil {
    return fmt.Errorf("source snapshot unavailable: %w", err)
}

Try / catch

inst, err := MaterializeGitUncommittedPack(ctx, tree, pack)
if err != nil {
    if strings.Contains(err.Error(), "get canonical checkout snapshot") {
        // inspect wrapped cause; retry or restart engine
    }
    return err
}

Prevention

When it happens

Trigger: Calling MaterializeGitUncommittedPack (via withGitUncommitted, e.g. host.directory(...).terminal or any uncommitted host directory load) when tree.Self().Snapshot.GetOrEval fails — the source directory snapshot cannot be resolved from the cache.

Common situations: The host directory was captured but its underlying git checkout snapshot was evicted or failed to build; context canceled mid-evaluation; an earlier pipeline stage errored leaving the LazyAccessor with an error result; cache/ref corruption after an engine crash.

Related errors


AI-assisted analysis of dagger/dagger@82ba2681db (2026-09-05). Data as JSON: /api/errors/d6b4c659deeaf855. Report an issue: GitHub.

Appendix: source

Thrown at core/git_hostdir.go:219

	dir.Dir.setValue("/.git")
	dir.Snapshot.setValue(snap)
	return dir, nil
}

// MaterializeGitUncommittedPack applies a client-produced binary patch of
// uncommitted changes (tracked modifications plus untracked files) to a
// canonical HEAD checkout and recreates lightweight markers for omitted
// untracked nested repositories. The result keeps HEAD's canonical .git and a
// dirty working tree suitable for LocalGitRepository.uncommitted.
func MaterializeGitUncommittedPack(ctx context.Context, tree dagql.ObjectResult[*Directory], pack *engineutil.GitUncommittedPack) (inst dagql.ObjectResult[*Directory], rerr error) {
	srv := dagql.CurrentDagqlServer(ctx)
	query, err := CurrentQuery(ctx)
	if err != nil {
		return inst, err
	}
	parent, err := tree.Self().Snapshot.GetOrEval(ctx, tree.Result)
	if err != nil {
		return inst, fmt.Errorf("get canonical checkout snapshot: %w", err)
	}
	treePath, err := tree.Self().Dir.GetOrEval(ctx, tree.Result)
	if err != nil {
		return inst, fmt.Errorf("get canonical checkout path: %w", err)
	}

	bkref, err := query.SnapshotManager().New(ctx, parent,
		bkcache.WithRecordType(bkclient.UsageRecordTypeRegular),
		bkcache.WithDescription("git uncommitted changes"))
	if err != nil {
		return inst, err
	}
	defer func() {
		if rerr != nil && bkref != nil {
			bkref.Release(context.WithoutCancel(ctx))
		}
	}()

View on GitHub (pinned to 82ba2681db)