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
- Inspect the wrapped (%w) cause in the error chain — it names the real failure in the snapshot evaluation
- Re-run the command; transient mount/cache evaluation failures often resolve on retry
- Restart the Dagger engine to clear corrupted cache state (dagger engine restart / prune cache)
- 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
- Always inspect the wrapped cause with errors.Unwrap / %w chain
- Keep engine cache healthy; avoid pruning concurrently with runs
- Retry transient snapshot evaluation failures
- Load host directories fresh rather than reusing long-lived results
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
- get canonical checkout path
- get git directory snapshot
- attach git bundle file: unexpected result %T
- attach git repository auth header
- attach git repository auth token
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)