helm/helm · error

missing runtimeConfig field

Error message

missing runtimeConfig field

What it means

Metadata.Validate (internal/plugin/metadata.go:90) requires a non-nil runtimeConfig field. runtimeConfig holds the runtime-specific execution settings - for 'subprocess' this is RuntimeConfigSubprocess (platformCommand, platformHooks, protocolCommands), for 'extism/v1' the wasm module config. It is decoded by convertMetadataRuntimeConfig before Validate runs.

Source

Thrown at internal/plugin/metadata.go:90

	if m.APIVersion == "" {
		errs = append(errs, errors.New("empty APIVersion"))
	}

	if m.Type == "" {
		errs = append(errs, errors.New("empty type field"))
	}

	if m.Runtime == "" {
		errs = append(errs, errors.New("empty runtime field"))
	}

	if m.Config == nil {
		errs = append(errs, errors.New("missing config field"))
	}

	if m.RuntimeConfig == nil {
		errs = append(errs, errors.New("missing runtimeConfig field"))
	}

	// Validate the config itself
	if m.Config != nil {
		if err := m.Config.Validate(); err != nil {
			errs = append(errs, fmt.Errorf("config validation failed: %w", err))
		}
	}

	// Validate the runtime config itself
	if m.RuntimeConfig != nil {
		if err := m.RuntimeConfig.Validate(); err != nil {
			errs = append(errs, fmt.Errorf("runtime config validation failed: %w", err))
		}
	}

	if len(errs) > 0 {
		return errors.Join(errs...)

View on GitHub (pinned to 2a29f1770b)

Solutions

1. Add a runtimeConfig block appropriate to the runtime, e.g. 'runtimeConfig:\n platformCommand:\n - command: ./myplugin' for subprocess
2. When migrating legacy plugins, map the legacy command/platformCommand and hooks into runtimeConfig (fromMetadataLegacy shows the mapping)
3. Ensure the runtimeConfig contents validate - RuntimeConfigSubprocess.Validate can add a wrapped 'runtime config validation failed' error

Example fix

# before
apiVersion: v1
name: myplugin
type: cli/v1
runtime: subprocess
version: 1.0.0
config:
  shortHelp: does a thing

# after
apiVersion: v1
name: myplugin
type: cli/v1
runtime: subprocess
version: 1.0.0
config:
  shortHelp: does a thing
runtimeConfig:
  platformCommand:
    - command: ./myplugin

func hasRuntimeConfig(pluginYAMLPath string) bool {
	b, err := os.ReadFile(pluginYAMLPath)
	if err != nil {
		return false
	}
	var probe struct {
		RuntimeConfig map[string]any `yaml:"runtimeConfig"`
	}
	return yaml.Unmarshal(b, &probe) == nil && probe.RuntimeConfig != nil
}

if err := md.Validate(); err != nil {
	if strings.Contains(err.Error(), "missing runtimeConfig field") {
		// add runtimeConfig (platformCommand/platformHooks for subprocess runtime)
	}
	return err
}

When it happens

Trigger: A v1 plugin.yaml without a 'runtimeConfig:' section (or explicitly null). Note that decoding happens first: for runtime 'subprocess' a missing runtimeConfig may also surface as a remarshal/unmarshal error; the 'missing runtimeConfig field' message comes from the metadata-level nil check.

Common situations: Legacy-format plugins being migrated: their platformCommand/command/hooks must move under runtimeConfig; authors writing the new format who stop at name/type/runtime/config; empty 'runtimeConfig:' line parsed as null.

Related errors

• empty APIVersion
• empty type field
• empty runtime field
• missing config field
• failed to extract plugin metadata from tarball: %w

AI-assisted analysis of helm/helm@2a29f1770b (2026-08-15). Data as JSON: /api/errors/cfd3c88aac63eff0. Report an issue: GitHub.