Support for Experimental.GraphsyncEnabled has been removed i

Error message

Support for Experimental.GraphsyncEnabled has been removed in Kubo 0.25.0, please remove this key. For more details see https://github.com/ipfs/kubo/pull/9747.

What it means

Experimental.GraphsyncEnabled support was removed in Kubo 0.25.0 (kubo PR #9747). Its UnmarshalJSON accepts an empty object or an explicit false (both treated as 'not set'), but any other value (notably true) is rejected with this error pointing at the removal PR.

Source

Thrown at config/types.go:585

type graphsyncEnabled doNotUse

var _ json.Unmarshaler = graphsyncEnabled(false)

func (graphsyncEnabled) UnmarshalJSON(b []byte) error {
	d := json.NewDecoder(bytes.NewReader(b))
	for {
		switch tok, err := d.Token(); err {
		case io.EOF:
			return nil
		case nil:
			switch tok {
			case json.Delim('{'), json.Delim('}'), false:
				// accept empty objects and false
				continue
			}
			//nolint
			return fmt.Errorf("Support for Experimental.GraphsyncEnabled has been removed in Kubo 0.25.0, please remove this key. For more details see https://github.com/ipfs/kubo/pull/9747.")
		default:
			return err
		}
	}
}

View on GitHub (pinned to 329838acdf)

Solutions

Remove the key: `ipfs config delete Experimental.GraphsyncEnabled` (or delete it from config.json).
If it must stay for scripted configs, set it to false: {"Experimental": {"GraphsyncEnabled": false}}.
Review https://github.com/ipfs/kubo/pull/9747 for what changed if you depended on graphswap behavior.

Example fix

// before (config.json)
{"Experimental": {"GraphsyncEnabled": true}}
// after
{}   // key removed entirely

Defensive patterns

Strategy: validation

Validate before calling

// detect stale GraphsyncEnabled before daemon start
func hasGraphsyncEnabled(cfg map[string]any) bool {
    exp, _ := cfg["Experimental"].(map[string]any)
    v, ok := exp["GraphsyncEnabled"]
    if !ok { return false }
    b, isBool := v.(bool)
    return isBool && b // only true is rejected
}

Type guard

func graphsyncKeySafe(cfg map[string]any) bool {
    exp, _ := cfg["Experimental"].(map[string]any)
    v, present := exp["GraphsyncEnabled"]
    if !present { return true }
    if b, ok := v.(bool); ok && !b { return true }
    if m, ok := v.(map[string]any); ok && len(m) == 0 { return true }
    return false
}

Try / catch

if err := node.Start(); err != nil {
    if strings.Contains(err.Error(), "Experimental.GraphsyncEnabled") {
        // delete the key (or set false) and restart
    }
}

Prevention

Remove Experimental.GraphsyncEnabled from configs and automation when upgrading to >=0.25
Set the key to false only if legacy scripts require its presence
Review kubo changelog/PR 9747 for removal context

When it happens

Trigger: Starting a node with config.json containing Experimental.GraphsyncEnabled: true, or any value other than false/empty object, on Kubo >= 0.25.

Common situations: Nodes that enabled graphsync for BITSWAP-over-graphsync experiments before 0.25; copied legacy configs; automation that still sets the flag.

Related errors

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