unknown config value, Migrations.Keep must be 'cache', 'pin'

Error message

unknown config value, Migrations.Keep must be 'cache', 'pin', or 'discard'

What it means

ReadMigrationConfig validates the Migrations.Keep config key, which controls how migration-affected data is treated ('cache', 'pin', or the default 'discard' behavior; 'keep' is accepted as an alias). A value outside the accepted set fails validation.

Source

Thrown at repo/fsrepo/migrations/migrations.go:150

	}

	cfgFile, err := os.Open(cfgPath)
	if err != nil {
		return nil, err
	}
	defer cfgFile.Close()

	err = json.NewDecoder(cfgFile).Decode(&cfg)
	if err != nil {
		return nil, err
	}

	switch cfg.Migration.Keep {
	case "":
		cfg.Migration.Keep = config.DefaultMigrationKeep
	case "discard", "cache", "keep":
	default:
		return nil, errors.New("unknown config value, Migrations.Keep must be 'cache', 'pin', or 'discard'")
	}

	if len(cfg.Migration.DownloadSources) == 0 {
		cfg.Migration.DownloadSources = config.DefaultMigrationDownloadSources
	}

	return &cfg.Migration, nil
}

// GetMigrationFetcher creates one or more fetchers from downloadSources.
// Multiple fetchers are wrapped in a MultiFetcher that rotates to the next
// gateway when one errors and quarantines failed gateways for the session.
//
// Deprecated: This function is used by legacy migration downloads and will be removed
// in a future version. Use RunHybridMigrations or RunEmbeddedMigrations instead.
func GetMigrationFetcher(downloadSources []string, distPath string, newIpfsFetcher func(string) Fetcher) (Fetcher, error) {
	const httpUserAgent = "kubo/migration"

View on GitHub (pinned to 329838acdf)

Solutions

Set Migrations.Keep in the repo config to exactly "cache", "pin", or "discard" (lowercase).
Run `ipfs config Migrations.Keep cache` (or pin/discard) instead of hand-editing JSON.
Remove the Migrations.Keep key entirely to fall back to the default.

Example fix

// before
"Migrations": { "Keep": "Pins" }
// after
"Migrations": { "Keep": "pin" }

Defensive patterns

Strategy: validation

Validate before calling

keep := cfg.Migration.Keep
if keep != "" && keep != "discard" && keep != "cache" && keep != "keep" {
    return fmt.Errorf("invalid Migrations.Keep: %q", keep)
}

Try / catch

cfg, err := cmd.ReadMigrationConfig()
if err != nil {
    if strings.Contains(err.Error(), "Migrations.Keep") {
        // fix config value
    }
}

Prevention

Use `ipfs config Migrations.Keep <value>` instead of editing JSON by hand
Keep values lowercase: cache, pin, discard
Omit the key to accept the default

When it happens

Trigger: Calling ReadMigrationConfig when the repo config contains Migrations.Keep set to anything other than "", "discard", "cache", or "keep" — e.g. a typo like "pins" or "Cache".

Common situations: Hand-editing the kubo config file and misspelling the value; scripts writing Migrations.Keep with wrong casing or an unexpected keyword; copying config from outdated documentation.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

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