grafana/k6 · error

unhandled extension type: %s

Error message

unhandled extension type: %s

What it means

versionDetailsWithExtensions classifies every registered extension by ext.Type into known kinds (OutputExtension, JSExtension, SecretSourceExtension, SubcommandExtension). The default branch is a forward-compatibility guard: if a binary registers an extension with a type this k6 build does not know, it returns "unhandled extension type: <type>" instead of silently dropping it from version details.

Source

Thrown at internal/cmd/version.go:205

				Version: e.Version,
			}

			infoMap[key] = info
			infoList = append(infoList, info)
		}

		switch e.Type {
		case ext.OutputExtension:
			info.Outputs = append(info.Outputs, e.Name)
		case ext.JSExtension:
			info.Imports = append(info.Imports, e.Name)
		case ext.SecretSourceExtension:
			// currently, no special handling is needed for secret source extensions
		case ext.SubcommandExtension:
			// currently, no special handling is needed for subcommand extensions
		default:
			// report unhandled extension type for future proofing
			return details, fmt.Errorf("unhandled extension type: %s", e.Type)
		}
	}

	details["extensions"] = infoList

	return details, nil
}

type versionCmd struct {
	gs     *state.GlobalState
	isJSON bool
}

func (c *versionCmd) run(cmd *cobra.Command, _ []string) error {
	if !c.isJSON {
		root := cmd.Root()
		root.SetArgs([]string{"--version"})
		_ = root.Execute()

View on GitHub (pinned to 93accf6570)

Solutions

1. Rebuild/upgrade so the k6 core handles the new extension type — add the case to internal/cmd/version.go upstream
2. For embedders, register only supported types (Output, JS, SecretSource, Subcommand) against the vendored k6
3. File an issue upstream if the unknown type comes from an official extension

Example fix

// before (embedding k6, registers an unknown kind)
ext.Register(ext.NewExtension(myUnknownKind, "myext", nil))
// after
ext.Register(ext.NewExtension(ext.JSExtension, "myext", myModule)) // use a known ext.Type

// Exhaustive guard for extension types before building version details
func knownExtensionType(t ext.Type) bool {
	switch t {
	case ext.OutputExtension, ext.JSExtension, ext.SecretSourceExtension, ext.SubcommandExtension:
		return true
	default:
		return false
	}
}

When it happens

Trigger: A custom xk6 build or embedded k6 registering an ext.Type outside the four handled cases (e.g. a newly introduced extension kind compiled against a different k6 core); version skew between the extension registrar and internal/cmd/version.go.

Common situations: k6 forks adding a new extension category without updating the version command; pre-release extension types used with an older vendored k6; embedding k6 as a library and registering custom extension kinds.

Related errors

• failed to get version details with extensions: %w
• unsupported extension type: %T
• extension already registered: %s
• Error while parsing selector `${selector}` - cannot use ${op
• failed to encode/output version details: %w

AI-assisted analysis of grafana/k6@93accf6570 (2026-08-15). Data as JSON: /api/errors/4008319fb7ace986. Report an issue: GitHub.