What causes "configuration is nil" in lima-vm/lima?

Ensure the instance config is loaded before creating the driver (load the limayaml first)

configuration is nil

Error message

configuration is nil

What it means

validateConfig requires a non-nil LimaYAML config before validating driver requirements. The VZ driver was asked to validate a nil configuration, meaning the instance config was never loaded or filled.

Source

Thrown at pkg/driver/vz/vz_driver_darwin.go:262

			content, err := bootLinuxFS.ReadFile(entryPath)
			if err != nil {
				return nil, err
			}

			scripts[entryPath] = content
		}
	}

	return scripts, nil
}

func (l *LimaVzDriver) Validate(_ context.Context) error {
	return validateConfig(l.Instance.Config)
}

func validateConfig(cfg *limatype.LimaYAML) error {
	if cfg == nil {
		return errors.New("configuration is nil")
	}
	macOSProductVersion, err := osutil.ProductVersion()
	if err != nil {
		return err
	}
	if macOSProductVersion.LessThan(*semver.New("13.0.0")) {
		return errors.New("VZ driver requires macOS 13 or higher to run")
	}
	if runtime.GOARCH == "amd64" && macOSProductVersion.LessThan(*semver.New("15.5.0")) {
		logrus.Warnf("vmType %s: On Intel Mac, macOS 15.5 or later is required to run Linux 6.12 or later. "+
			"Update macOS, or change vmType to `qemu` if the VM does not start up. (https://github.com/lima-vm/lima/issues/3334)",
			*cfg.VMType)
	}
	if cfg.MountType != nil && *cfg.MountType == limatype.NINEP {
		return fmt.Errorf("field `mountType` must be %#q or %#q for VZ driver , got %#q", limatype.REVSSHFS, limatype.VIRTIOFS, *cfg.MountType)
	}
	if cfg.TPM != nil && *cfg.TPM {
		return errors.New("field `tpm` is not supported on VZ driver")

View on GitHub (pinned to dd909d0973)

Solutions

Ensure the instance config is loaded before creating the driver (load the limayaml first)
Recreate the instance if its metadata in ~/.lima is corrupted: `limactl delete <name> --force`
If calling the API programmatically, pass a valid *limatype.LimaYAML
Report to lima-vm/lima if hit through normal `limactl start` usage — it indicates an internal bug

Example fix

// before
driver.Validate(ctx) // cfg is nil
// after
cfg, err := limayaml.Load(yamlPath)
if err != nil { return err }
instance.Config = cfg
driver.Validate(ctx)

Defensive patterns

Strategy: type-guard

Validate before calling

if cfg == nil {
    return errors.New("instance config must be loaded before driver validation")
}

Type guard

func hasConfig(inst *limatype.Instance) bool {
    return inst != nil && inst.Config != nil
}

Try / catch

if err := validate(); err != nil && err.Error() == "configuration is nil" {
    // load the instance config, attach it, and call validate again
}

Prevention

Always load limayaml before instantiating the driver
If scripting the API, never call driver methods on partially built instances
Treat this error as an internal bug if seen via normal limactl usage and report it

When it happens

Trigger: LimaVzDriver.Validate() is called (via Validate or fillConfig) with l.Instance.Config == nil, i.e. the instance YAML was not loaded before driver validation.

Common situations: Programming/internal error: instance created without loading its config; corrupted instance metadata in LIMA_HOME; calling the driver API directly without a loaded config.

Related errors

AI-assisted analysis of lima-vm/lima@dd909d0973 (2026-09-01). Data as JSON: /api/errors/85a816ceca07fa57. Report an issue: GitHub.