What causes "failed to decode file as config" in ipfs/kubo?

Validate the file first: `jq empty new-config.json` — fix any JSON syntax errors it reports

failed to decode file as config

Error message

failed to decode file as config

What it means

`ipfs config replace` decodes the input file into a config.Config struct. This error is returned when the file is not valid JSON or its structure does not match the config schema, discarding the detailed decode error. Note it does NOT use %w, so the underlying JSON error is not shown.

Source

Thrown at core/commands/config.go:651

	if !ok {
		return "", errors.New("private key in config was not a string")
	}
	ident := config.Identity{PrivKey: pkstr}
	pk, err := ident.DecodePrivateKey("")
	if err != nil {
		return "", fmt.Errorf("failed to decode PrivKey: %w", err)
	}
	id, err := peer.IDFromPrivateKey(pk)
	if err != nil {
		return "", fmt.Errorf("failed to derive PeerID from PrivKey: %w", err)
	}
	return id, nil
}

func replaceConfig(r repo.Repo, file io.Reader) error {
	var newCfg config.Config
	if err := json.NewDecoder(file).Decode(&newCfg); err != nil {
		return errors.New("failed to decode file as config")
	}

	// Handle Identity.PrivKey (secret)

	if len(newCfg.Identity.PrivKey) != 0 {
		return errors.New("setting private key with API is not supported")
	}

	keyF, err := getConfig(r, config.PrivKeySelector)
	if err != nil {
		return errors.New("failed to get PrivKey")
	}

	pkstr, ok := keyF.Value.(string)
	if !ok {
		return errors.New("private key in config was not a string")
	}

View on GitHub (pinned to 329838acdf)

Solutions

Validate the file first: `jq empty new-config.json` — fix any JSON syntax errors it reports
Ensure it's a full config in kubo's JSON schema: generate a reference with `ipfs config show > ref.json` and diff structure
Check the file isn't HTML/empty: `head -c 200 new-config.json` — re-download or re-export if so
Remember replace also refuses to set Identity.PrivKey via the API; keep the file's Identity handling in mind (see the 'setting private key with API is not supported' error)

Example fix

// before
ipfs config replace config.yaml   # YAML not accepted
// after
ipfs config show > backup.json
jq '. + {"Addresses": ...}' backup.json > new.json && jq empty new.json
ipfs config replace new.json

Defensive patterns

Strategy: validation

Validate before calling

jq empty new-config.json && jq -e 'has("Addresses") and has("Identity") or true' new-config.json && head -c 1 new-config.json | grep -q '{' && echo "looks like JSON config"

Try / catch

var newCfg config.Config
if err := json.NewDecoder(file).Decode(&newCfg); err != nil {
    return fmt.Errorf("failed to decode file as config: %w", err) // preserve the real cause
}

Prevention

Validate the file with `jq empty` before `ipfs config replace`
Build the replacement from `ipfs config show` output, not hand-written YAML/TOML
Check the file starts with '{' — HTML error pages or empty files fail here
Keep full configs (not fragments); replace expects a complete config structure

When it happens

Trigger: Running `ipfs config replace <file>` where the file contains invalid JSON, YAML/TOML instead of JSON, a partial config with wrong field types, or empty/HTML content (e.g. a downloaded error page).

Common situations: Redirecting `ipfs config show` output through tools that alter it; downloading a config from a URL that returned an HTML error page; replacing with a partial config fragment instead of a full config.

Understand the failure class

Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

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