containerd/containerd · error

failed to create file %q: %w

Error message

failed to create file %q: %w

What it means

The mkfs transform opens (and creates) the backing file with r.OpenFile(path, O_RDWR|O_CREATE|O_TRUNC, 0640) before running the mkfs binary; if that open fails, the underlying error is wrapped with the file path. This is a filesystem-level create/open failure, not a formatting failure.

Source

Thrown at core/mount/manager/mkfs.go:121

		// Check fs
		switch fs {
		case "ext2", "ext3", "ext4":
			binary = fmt.Sprintf("mkfs.%s", fs)
			if id != "" {
				createArgs = append(createArgs, []string{"-U", id}...)
			}
		case "xfs":
			binary = "mkfs.xfs"
			if id != "" {
				createArgs = append(createArgs, []string{"-m", fmt.Sprintf("uuid=%s", id)}...)
			}
		default:
			return mount.Mount{}, fmt.Errorf("unsupported filesystem %q: %w", fs, errdefs.ErrInvalidArgument)
		}

		f, err := r.OpenFile(subpath, os.O_RDWR|os.O_CREATE|os.O_TRUNC, 0640)
		if err != nil {
			return mount.Mount{}, fmt.Errorf("failed to create file %q: %w", m.Source, err)
		}

		createArgs = append(createArgs, f.Name())

		err = f.Truncate(size)
		f.Close()
		if err != nil {
			return mount.Mount{}, fmt.Errorf("failed to truncate file %q: %w", m.Source, err)
		}

		if err := createWritableImage(ctx, binary, createArgs...); err != nil {
			return mount.Mount{}, fmt.Errorf("failed format %q: %w", m.Source, err)
		}
	} else {
		return mount.Mount{}, fmt.Errorf("failed to stat %q: %w", m.Source, err)
	}

	return m, nil

View on GitHub (pinned to 4246446a2b)

Solutions

1. Check the wrapped cause (errors.Is fs.ErrPermission/fs.ErrNotExist) and fix permissions or create missing parent directories
2. Ensure the configured root path is writable and has free space (df, mount -o rw)
3. Verify the source path resolves inside the root and its parent exists
4. Check for MAC policies (SELinux/AppArmor) blocking file creation and adjust labels/profiles

Example fix

// before
root: "/mnt/ro-loopbacks" // mounted read-only -> OpenFile fails
// after
mount -o remount,rw /mnt/ro-loopbacks // or configure root on a writable volume

target := filepath.Join(root, subpath)
if err := os.MkdirAll(filepath.Dir(target), 0755); err != nil {
	return err
}
f, err := os.OpenFile(target, os.O_RDWR|os.O_CREATE|os.O_TRUNC, 0640)
if err != nil {
	return fmt.Errorf("cannot create backing file %s: %w", target, err)
}
f.Close()

m, err := manager.Transform(ctx, mount)
if err != nil && strings.Contains(err.Error(), "failed to create file") {
	if errors.Is(err, fs.ErrPermission) || errors.Is(err, fs.ErrNotExist) {
		// fix root writability / parent dirs before retrying
	}
}

When it happens

Trigger: Transform reaches the OpenFile call (valid root matched, options parsed) and OpenFile returns an error: parent dir missing, permission denied, read-only filesystem, ENOSPC, or the root backend rejecting O_TRUNC on existing files.

Common situations: Root filesystem full or read-only; subpath's parent directories don't exist under the root; process lacks write permission to the root directory; SELinux/AppArmor denying file creation in the configured root path.

Related errors

• failed to activate mounts: %w
• failed to create directory %q: %w
• failed to stat %q: %w
• no root %q configured for mkfs: %w
• bad option %s: %w

AI-assisted analysis of containerd/containerd@4246446a2b (2026-09-02). Data as JSON: /api/errors/dbc8597facd629f1. Report an issue: GitHub.