What causes "%s not found" in ipfs/kubo?

Treat the error as authoritative absence: check errors.Is/string match and fall back to a default value

%s not found

Error message

%s not found

What it means

MapGetKV returns this error when a segment of the dotted key does not exist in the config map at its level. The message contains the full path traversed up to and including the missing segment (e.g. "Datastore.StorageMax" missing produces "X not found" for the absent part). It is the ordinary "no such config key" error for map-based config access.

Source

Thrown at repo/common/common.go:31

	parts := strings.Split(key, ".")
	for i, part := range parts {
		sofar := strings.Join(parts[:i], ".")

		mcursor, ok = cursor.(map[string]any)
		if !ok {
			return nil, fmt.Errorf("%s key is not a map", sofar)
		}

		cursor, ok = mcursor[part]
		if !ok {
			// Construct the current path traversed to print a nice error message
			var path string
			if len(sofar) > 0 {
				path += sofar + "."
			}
			path += part
			return nil, fmt.Errorf("%s not found", path)
		}
	}
	return cursor, nil
}

func MapSetKV(v map[string]any, key string, value any) error {
	var ok bool
	var mcursor map[string]any
	var cursor any = v

	parts := strings.Split(key, ".")
	for i, part := range parts {
		mcursor, ok = cursor.(map[string]any)
		if !ok {
			sofar := strings.Join(parts[:i], ".")
			return fmt.Errorf("%s key is not a map", sofar)
		}

View on GitHub (pinned to 329838acdf)

Solutions

Treat the error as authoritative absence: check errors.Is/string match and fall back to a default value
List available keys (ipfs config show) to verify the exact spelling/casing of the key
Create the key first with MapSetKV/SetConfigKey if it is optional and legitimately absent
Confirm version compatibility: keys added in newer releases do not exist in older configs

Example fix

// before
v, err := MapGetKV(cfg, "Datastore.StorageMax")
if err != nil { return err } // fails when key absent
// after
v, err := MapGetKV(cfg, "Datastore.StorageMax")
if err != nil {
    v = "10GB" // default when not found
}

Defensive patterns

Strategy: validation

Validate before calling

func hasKey(v map[string]any, dotted string) bool {
    cur := any(v)
    parts := strings.Split(dotted, ".")
    for i, part := range parts {
        m, ok := cur.(map[string]any)
        if !ok {
            return false
        }
        cur, ok = m[part]
        if !ok {
            return false
        }
        _ = i
    }
    return true
}

Try / catch

v, err := GetConfigKey(cfg, "Swarm.RelayService.Enabled")
if err != nil && strings.HasSuffix(err.Error(), "not found") {
    v = defaultRelayEnabled // absent key means default
}

Prevention

Verify exact key spelling with ipfs config show before programmatic access
Treat not-found as 'use default' for optional keys instead of failing
Pin minimum kubo versions for keys introduced in newer releases
Set optional keys explicitly so downstream readers never see absence

When it happens

Trigger: GetConfigKey with a key that was never set: typos ("Addresses.APIs" vs "Addresses.API"), probing optional keys that are absent from the on-disk config, keys removed/renamed between versions, or defaults not yet materialized into the map.

Common situations: ipfs config get on a missing field; tooling reading optional config (e.g. Autosave, custom plugin sections) that the user never wrote; automation expecting a key introduced in a newer kubo while running an older node.

Related errors

AI-assisted analysis of ipfs/kubo@329838acdf (2026-09-03). Data as JSON: /api/errors/388af810e4168cd5. Report an issue: GitHub.