What causes "failed to get file snapshot for mount %d" in dagger/dagger?

Diagnose the underlying snapshot failure by evaluating the File standalone (e.g. .Contents())

failed to get file snapshot for mount %d

Error message

failed to get file snapshot for mount %d

What it means

The File handle for the mount exists but its Snapshot lazy field failed to resolve, so no content-addressed reference is available to bind-mount. Equivalent to the directory snapshot failure but on the file path.

Source

Thrown at core/container_exec.go:867

				mountState.Selector = selector
			}
			ref, ok := dir.Snapshot.Peek()
			if !ok {
				return materialized, fmt.Errorf("failed to get directory snapshot for mount %d", i)
			}
			mountState.SourceRef = ref

		case ctrMount.FileSource != nil:
			file, ok := ctrMount.FileSource.Peek()
			if !ok || file == nil {
				return materialized, fmt.Errorf("mount %d has nil file source", i)
			}
			if selector, ok := file.File.Peek(); ok {
				mountState.Selector = selector
			}
			ref, ok := file.Snapshot.Peek()
			if !ok {
				return materialized, fmt.Errorf("failed to get file snapshot for mount %d", i)
			}
			mountState.SourceRef = ref

		case ctrMount.CacheSource != nil:
			cacheSrc := ctrMount.CacheSource
			if cacheSrc.Volume.Self() == nil {
				return materialized, fmt.Errorf("mount %d has nil cache volume source", i)
			}
			if cacheSrc.Volume.Self().getSnapshot() == nil {
				if err := cacheSrc.Volume.Self().InitializeSnapshot(ctx); err != nil {
					return materialized, fmt.Errorf("initialize cache volume snapshot for mount %d: %w", i, err)
				}
			}
			cacheSnapshot := cacheSrc.Volume.Self().getSnapshot()
			if cacheSnapshot == nil {
				return materialized, fmt.Errorf("mount %d has nil cache volume snapshot", i)
			}
			mountState.SourceRef = cacheSnapshot

View on GitHub (pinned to 82ba2681db)

Solutions

Diagnose the underlying snapshot failure by evaluating the File standalone (e.g. .Contents())
Retry the producing step; transient cache/blob errors are often resolved by re-solve
Force evaluation with .Sync()/contents read before mounting to fail fast with a clearer error
Avoid carrying File handles across engine restarts or GC-pruned cache states

Example fix

// before
ctr = ctr.WithMountedFile("/bin/tool", staleFile)
// after
if _, err := staleFile.Size(ctx); err != nil { return err }
ctr = ctr.WithMountedFile("/bin/tool", staleFile)

Defensive patterns

Strategy: validation

Validate before calling

if _, err := file.Size(ctx); err != nil {
    return fmt.Errorf("file snapshot unavailable: %w", err)
}
ctr = ctr.WithMountedFile(path, file)

Try / catch

if _, err := ctr.Sync(ctx); err != nil {
    if strings.Contains(err.Error(), "failed to get file snapshot") {
        // retry after re-solving the producing step
    }
    return err
}

Prevention

Read file contents/size beforehand to force snapshot resolution
Retry transient cache/blob failures
Do not reuse File handles across engine restarts

When it happens

Trigger: WithMountedFile where the File's snapshot evaluation failed (upstream solve error, context cancellation, cache eviction) and is only detected when the exec runs.

Common situations: Transient engine/cache failures; timeouts while exporting file blobs; using a File from a different engine instance; pruned blobs behind a long-lived handle.

Related errors

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