ipfs/kubo · error

failed to set config value: %s (maybe use --json?)

Error message

failed to set config value: %s (maybe use --json?)

What it means

Wraps an error from `r.SetConfigKey(key, value)` during `ipfs config <key> <value>`. Most often the provided plain-string value cannot be unmarshaled into the config field's Go type (e.g. writing a bare string into a field that expects an array or object). The 'maybe use --json?' hint points at passing the value as JSON so it can be deserialized into the correct type.

Source

Thrown at core/commands/config.go:596

	// Load full config for resolution
	fullCfg, err := r.Config()
	if err != nil {
		return nil, fmt.Errorf("failed to load config: %q", err)
	}

	// Expand auto values based on the key
	expandedValue := fullCfg.ExpandConfigField(key, value)

	return &ConfigField{
		Key:   key,
		Value: expandedValue,
	}, nil
}

func setConfig(r repo.Repo, key string, value any) (*ConfigField, error) {
	err := r.SetConfigKey(key, value)
	if err != nil {
		return nil, fmt.Errorf("failed to set config value: %s (maybe use --json?)", err)
	}
	return getConfig(r, key)
}

// parseEditorCommand parses the EDITOR environment variable into command and arguments
func parseEditorCommand(editor string) ([]string, error) {
	return shlex.Split(editor, true)
}

func editConfig(filename string) error {
	editor := os.Getenv("EDITOR")
	if editor == "" {
		return errors.New("ENV variable $EDITOR not set")
	}

	editorAndArgs, err := parseEditorCommand(editor)
	if err != nil {
		return fmt.Errorf("cannot parse $EDITOR value: %s", err)

View on GitHub (pinned to 329838acdf)

Solutions

1. Re-run with --json: `ipfs config --json Addresses.Swarm '["/ip4/0.0.0.0/tcp/4001"]'`
2. Check the field's expected type in docs/config.md and supply matching JSON
3. For array appends/replacements use `ipfs config --json` with a full array value
4. Check the underlying error: if it's a permission issue, fix ownership of $IPFS_PATH/config.json (stop the daemon first if it's a lock/permission conflict)

Example fix

// before
ipfs config Addresses.Swarm /ip4/0.0.0.0/tcp/4001
// after
ipfs config --json Addresses.Swarm '["/ip4/0.0.0.0/tcp/4001"]'

ipfs config --json Addresses.Swarm '["/ip4/0.0.0.0/tcp/4001"]'  # use --json for non-string fields

err := r.SetConfigKey(key, value)
if err != nil {
    return fmt.Errorf("failed to set %s: %w (did you need --json?)", key, err)
}

When it happens

Trigger: `ipfs config Addresses.Swarm '/ip4/...'` — Swarm is an array, so a plain string fails; setting a nested object key with a scalar; setting a value whose type doesn't match the config schema; repo config file not writable.

Common situations: Users trying to set array-valued options (Addresses.Swarm, Bootstrap, DNSLink.Resolvers) without --json; setting keys with case mistakes; config read-only because the daemon runs as a different user.

Related errors

• failed to unmarshal json. %s
• failed to decode file as config
• invalid configuration profile: %s
• failure to decode config: %w
• invalid flag value: %d

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