cannot use diskImage: remote URLs not supported, only local

Error message

cannot use diskImage: remote URLs not supported, only local files can be specified

What it means

ValidateConfig rejects a diskImage value that starts with http:// or https://. The check is a plain strings.HasPrefix test; colima's image pipeline only handles local files, so remote URLs must be downloaded by the user before being referenced.

Source

Thrown at config/configmanager/configmanager.go:87

		return fmt.Errorf("vmType 'krunkit' is only available on macOS with Apple Silicon")
	}
	if _, ok := validVMTypes[c.VMType]; !ok {
		return fmt.Errorf("invalid vmType: '%s'", c.VMType)
	}
	if c.VMType == "qemu" {
		if err := util.AssertQemuImg(); err != nil {
			return fmt.Errorf("cannot use vmType: '%s', error: %w", c.VMType, err)
		}
	}
	if c.VMType == "krunkit" {
		if err := util.AssertKrunkit(); err != nil {
			return fmt.Errorf("cannot use vmType: '%s', error: %w", c.VMType, err)
		}
	}

	if c.DiskImage != "" {
		if strings.HasPrefix(c.DiskImage, "http://") || strings.HasPrefix(c.DiskImage, "https://") {
			return fmt.Errorf("cannot use diskImage: remote URLs not supported, only local files can be specified")
		}
	}

	if _, ok := validPortForwarders[c.PortForwarder]; !ok {
		return fmt.Errorf("invalid port forwarder: '%s'", c.PortForwarder)
	}

	if c.Network.GatewayAddress != nil {
		if err := validateGatewayAddress(c.Network.GatewayAddress); err != nil {
			return err
		}
	}

	if err := validateMounts(c.Mounts); err != nil {
		return err
	}

	return nil

View on GitHub (pinned to c3a5f9184d)

Solutions

Download the image first (curl -LO <url>) and set diskImage to the absolute local path
Prefer omitting diskImage entirely to use colima's default image workflow
Confirm the local path exists and is readable before starting

Example fix

# before
diskImage: https://cloud-images.ubuntu.com/jammy/jammy-server-cloudimg-arm64.img

# after
curl -LO https://cloud-images.ubuntu.com/jammy/jammy-server-cloudimg-arm64.img
diskImage: /Users/me/Downloads/jammy-server-cloudimg-arm64.img

Defensive patterns

Strategy: validation

Validate before calling

if strings.HasPrefix(c.DiskImage, "http://") || strings.HasPrefix(c.DiskImage, "https://") {
    // download to a local path first, e.g. curl -LO, then set c.DiskImage to the file
}

Try / catch

if err := configmanager.ValidateConfig(c); err != nil {
    if strings.Contains(err.Error(), "remote URLs not supported") {
        // fetch the image locally and point diskImage at the file
    }
}

Prevention

Pre-download images into a stable local directory referenced by config
Prefer omitting diskImage unless a custom local image is truly needed
Automate image fetches in provisioning scripts, not in colima config

When it happens

Trigger: Setting diskImage to a remote URL in colima.yaml or passing 'colima start --disk-image=https://...' with any http/https prefixed string.

Common situations: Pointing at a cloud image (e.g. an Ubuntu cloud img URL) expecting colima to fetch it; migrating from tooling that accepts URLs for base images; pasting a URL where a local path was intended.

Related errors

AI-assisted analysis of abiosoft/colima@c3a5f9184d (2026-08-15). Data as JSON: /api/errors/5e1a1134aae2dd81. Report an issue: GitHub.