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

Check spelling of every segment in the dotted key

%s not found

Error message

%s not found

What it means

CheckKey() validates a dotted key against the config structure; if a segment is not found in the current map (and no "*" wildcard default section matches), the key does not exist in the schema. The error reports the full path up to and including the missing segment.

Source

Thrown at config/config.go:257

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

		cursor, ok = mapCursor[part]
		if !ok {
			// If the config sections is a map, validate against the default entry.
			if cursor, ok = mapCursor["*"]; ok {
				continue
			}
			path := strings.Join(parts[:i+1], ".")
			return fmt.Errorf("%s not found", path)
		}
	}
	return nil
}

View on GitHub (pinned to 329838acdf)

Solutions

Check spelling of every segment in the dotted key
Run `ipfs config show` or consult docs/config.md for the valid key names
Verify the relevant plugin providing the config section is loaded
Confirm the key exists in the kubo version in use (schema changes across releases)

Example fix

// before
err := CheckKey(cfg, "Pubsub.Enbled") // typo
// after
err := CheckKey(cfg, "Pubsub.Enabled")

Defensive patterns

Strategy: validation

Validate before calling

if err := config.CheckKey(cfg, "Pubsub.Enabled"); err != nil {
	// key rejected: check docs/config.md for the valid name before setting
	log.Fatalf("invalid config key: %v", err)
}

Try / catch

if err := SetConfigKey(cfg, key, val); err != nil {
	if strings.HasSuffix(err.Error(), "not found") {
		return fmt.Errorf("unknown config key %q (check docs/config.md and kubo version): %w", key, err)
	}
	return err
}

Prevention

Cross-check every key against docs/config.md for the kubo version in use
Watch for renames across upgrades and migrate config keys on version bumps
Spell-check dotted paths; most rejections are typos
Verify plugin-provided sections exist (plugin loaded) before referencing them

When it happens

Trigger: Calling CheckKey or SetConfigKey with a key segment that does not exist in the config schema, e.g. "Adresses.API" (typo) or "Foo.Bar" for a nonexistent section, with no wildcard ("*") section covering it.

Common situations: Typos in CLI `ipfs config` key arguments; using config keys from an older/newer kubo version that were renamed or removed; scripts referencing plugin-provided sections when the plugin is not loaded.

Related errors

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