ipfs/kubo · error

failure to decode config: %w

Error message

failure to decode config: %w

What it means

ReadConfigFile wraps JSON decoding failures with "failure to decode config: %w". The file exists and opens, but its contents are not valid JSON or do not match the expected config structure. The wrapped error preserves the exact json decoder problem (offset, type mismatch).

Source

Thrown at config/serialize/serialize.go:31

	"github.com/facebookgo/atomicfile"
)

// ErrNotInitialized is returned when we fail to read the config because the
// repo doesn't exist.
var ErrNotInitialized = errors.New("ipfs not initialized, please run 'ipfs init'")

// ReadConfigFile reads the config from `filename` into `cfg`.
func ReadConfigFile(filename string, cfg any) error {
	f, err := os.Open(filename)
	if err != nil {
		if os.IsNotExist(err) {
			err = ErrNotInitialized
		}
		return err
	}
	defer f.Close()
	if err := json.NewDecoder(f).Decode(cfg); err != nil {
		return fmt.Errorf("failure to decode config: %w", err)
	}
	return nil
}

// WriteConfigFile writes the config from `cfg` into `filename`.
func WriteConfigFile(filename string, cfg any) error {
	err := os.MkdirAll(filepath.Dir(filename), 0o755)
	if err != nil {
		return err
	}

	f, err := atomicfile.New(filename, 0o600)
	if err != nil {
		return err
	}
	defer f.Close()

	return encode(f, cfg)

View on GitHub (pinned to 329838acdf)

Solutions

1. Validate the file with `jq . $IPFS_PATH/config` (or config.json / libp2p-resource-limit-overrides.json) to find the syntax error and fix it.
2. Restore from a backup or re-run the failed `ipfs config` command.
3. As a last resort, run `ipfs init` in a fresh IPFS_PATH and re-apply settings; the wrapped json error message shows the byte offset to inspect.

Example fix

// before: $IPFS_PATH/config
{"Identity": {"PeerID": "12D3...,}   // trailing comma/missing brace
// after (valid JSON)
{"Identity": {"PeerID": "12D3K..."}}

raw, err := os.ReadFile(cfgPath)
if err == nil {
    var v map[string]any
    if jerr := json.Unmarshal(raw, &v); jerr != nil {
        return fmt.Errorf("config file %s is not valid JSON: %w", cfgPath, jerr)
    }
}

var cfg config.Config
if err := serialize.ReadConfigFile(path, &cfg); err != nil {
    var dec *json.SyntaxError
    if errors.As(err, &dec) { log.Fatalf("fix config JSON at offset %d: %v", dec.Offset, dec) }
    return err
}

When it happens

Trigger: Any caller (Load, SetConfig, GetConfigKey, SetConfigKey, openUserResourceOverrides) reading a config file whose content is malformed JSON, truncated after a crash, or whose fields have incompatible types (e.g. a string where a number is expected).

Common situations: Hand-editing config.json and leaving a syntax error, interrupted `ipfs config` writes or power loss leaving a partial file, using non-JSON values with `ipfs config --json` incorrectly, or template tools writing placeholders into the file.

Related errors

• invalid flag value: %d
• failed to unmarshal %q into a flag: must be null/undefined,
• invalid priority value: %d
• mountFuse: GetConfig() failed: %s
• %s path cannot be empty

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