dagger/dagger · error

failed to create new copy ref: %w

Error message

failed to create new copy ref: %w

What it means

In localFS.Sync, when not syncing parents-only (forParents=false), a fresh cache ImmutableRef is allocated with cacheManager.New(ctx, nil) to hold the copied data. If the cache manager cannot allocate the ref, the error is wrapped as "failed to create new copy ref". It indicates the engine's content cache refused/failed to create a new mutable record.

Source

Thrown at engine/filesync/localfs.go:176

//
// NOTE: This currently does not handle resetting parent dir modtimes to match the client. This matches
// upstream for now and avoids extra performance overhead + complication until a need for those modtimes
// matching the client's is proven.
func (local *localFS) Sync( //nolint:gocyclo
	ctx context.Context,
	remote ReadFS,
	cacheManager bkcache.Accessor,
	forParents bool,
) (_ bkcache.ImmutableRef, _ digest.Digest, rerr error) {
	var newCopyRef bkcache.MutableRef       // the mutable ref we will copy into with the frozen files+dirs if needed
	var cacheCtx bkcontenthash.CacheContext // track file+dir hashes

	// skip creating a cache ref if we're only syncing parent dirs
	if !forParents {
		var err error
		newCopyRef, err = cacheManager.New(ctx, nil)
		if err != nil {
			return nil, "", fmt.Errorf("failed to create new copy ref: %w", err)
		}
		defer func() {
			ctx := context.WithoutCancel(ctx)
			if newCopyRef != nil {
				if err := newCopyRef.Release(ctx); err != nil {
					rerr = errors.Join(rerr, fmt.Errorf("failed to release copy ref: %w", err))
				}
			}
		}()

		newCopyMD, ok := any(newCopyRef).(bkcache.RefMetadata)
		if !ok {
			return nil, "", fmt.Errorf("copy ref metadata: unexpected ref type %T", newCopyRef)
		}
		cacheCtx, err = bkcontenthash.GetCacheContext(ctx, newCopyMD)
		if err != nil {
			return nil, "", fmt.Errorf("failed to get cache context: %w", err)
		}

View on GitHub (pinned to 82ba2681db)

Solutions

1. Check the wrapped cause: if ENOSPC, free space on the engine cache volume (dagger engine prune).
2. Restart the engine / clear the cache if the buildkit cache DB is corrupted.
3. Avoid cancelling the client context during sync; retry with a clean context.
4. Verify the cache volume is writable in the engine container configuration.

// preflight: ensure the engine cache volume has free space and is writable
// df -h <cache-dir> && touch <cache-dir>/.writetest && rm <cache-dir>/.writetest

newRef, err := cacheManager.New(ctx, nil)
if err != nil {
    if errors.Is(err, context.Canceled) {
        return fmt.Errorf("sync cancelled during cache ref allocation; retry with a clean context")
    }
    return fmt.Errorf("check engine cache volume (space/permissions/corruption): %w", err)
}

When it happens

Trigger: cacheManager.New(ctx, nil) failing during a normal host-directory sync: cache backend I/O error, context cancelled mid-allocation, or cache store corrupted/full.

Common situations: Engine disk full (ENOSPC on the cache volume), corrupted buildkit cache database, context cancellation (Ctrl-C) racing the allocation, container running with a read-only cache mount.

Related errors

• snapshotmanager.New failed: %w
• failed to sync: %w
• failed to release copy ref: %w
• copy ref metadata: unexpected ref type %T
• reopen persisted client filesync mirror snapshot %q: %w

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