go-kratos/kratos · error

unsupported key: %s format: %s

Error message

unsupported key: %s format: %s

What it means

When the config decoder processes a loaded key it looks up a codec by the key's format (usually derived from the file extension) via encoding.GetCodec; if no codec is registered for that format, decoding fails and the key and format are reported. Extensions without a registered codec package (e.g. toml, ini) trigger it.

Source

Thrown at config/options.go:96

func defaultDecoder(src *KeyValue, target map[string]any) error {
	if src.Format == "" {
		// expand key "aaa.bbb" into map[aaa]map[bbb]interface{}
		keys := strings.Split(src.Key, ".")
		for i, k := range keys {
			if i == len(keys)-1 {
				target[k] = src.Value
			} else {
				sub := make(map[string]any)
				target[k] = sub
				target = sub
			}
		}
		return nil
	}
	if codec := encoding.GetCodec(src.Format); codec != nil {
		return codec.Unmarshal(src.Value, &target)
	}
	return fmt.Errorf("unsupported key: %s format: %s", src.Key, src.Format)
}

func newActualTypesResolver(enableConvertToType bool) func(map[string]any) error {
	return func(input map[string]any) error {
		mapper := mapper(input)
		return resolver(input, mapper, enableConvertToType)
	}
}

// defaultResolver resolve placeholder in map value,
// placeholder format in ${key:default}.
func defaultResolver(input map[string]any) error {
	mapper := mapper(input)
	return resolver(input, mapper, false)
}

func resolver(input map[string]any, mapper func(name string) string, toType bool) error {
	var resolve func(map[string]any) error

View on GitHub (pinned to 668db92c2c)

Solutions

1. Import (blank) the package that registers the codec for that format so its init runs
2. Rename the file to an extension with a registered codec (json/yaml)
3. Register your own codec implementing encoding.Codec and map the extension to it

Example fix

// before - config.toml loaded, no codec registered for "toml"

// after
import "github.com/go-kratos/kratos/v3/encoding"

func init() { encoding.RegisterCodec("toml", &tomlCodec{}) }
// or blank-import a package that registers the codec

format := strings.TrimPrefix(filepath.Ext(path), ".")
if encoding.GetCodec(format) == nil {
    return fmt.Errorf("no codec for %s; register one or rename the file", path)
}

When it happens

Trigger: Loading a config file whose extension maps to a format with no registered codec — encoding.GetCodec(src.Format) returns nil — such as adding a .toml or .ini file without importing/registering a codec for that format.

Common situations: Adding config files in formats the app never imported codecs for; custom extensions like .conf; renaming files to extensions the project does not register.

Related errors

• config: merge dst must be *map[string]interface{}, got %T
• type assert to %v failed
• kubernetes Object not ConfigMap
• ErrorCode: %d
• RegisterInstance err %v,%v

AI-assisted analysis of go-kratos/kratos@668db92c2c (2026-08-16). Data as JSON: /api/errors/7d6c7a1756535619. Report an issue: GitHub.