experimental pubsub feature not enabled, run daemon with --e

Error message

experimental pubsub feature not enabled, run daemon with --enable-pubsub-experiment to use

What it means

PubSubAPI.checkNode guards every pubsub operation: if the node was constructed without the experimental pubsub feature, api.pubSub is nil and the call fails immediately. PubSub is opt-in in Kubo because it is experimental, so the daemon (or node constructor) must explicitly enable it.

Source

Thrown at core/coreapi/pubsub.go:100

	}

	_, err = api.checkNode()
	if err != nil {
		return nil, err
	}

	//nolint deprecated
	sub, err := api.pubSub.Subscribe(topic)
	if err != nil {
		return nil, err
	}

	return &pubSubSubscription{sub}, nil
}

func (api *PubSubAPI) checkNode() (routing.Routing, error) {
	if api.pubSub == nil {
		return nil, errors.New("experimental pubsub feature not enabled, run daemon with --enable-pubsub-experiment to use")
	}

	err := api.checkOnline(false)
	if err != nil {
		return nil, err
	}

	return api.routing, nil
}

func (sub *pubSubSubscription) Close() error {
	sub.subscription.Cancel()
	return nil
}

func (sub *pubSubSubscription) Next(ctx context.Context) (coreiface.PubSubMessage, error) {
	ctx, span := tracing.Span(ctx, "CoreAPI.PubSubSubscription", "Next")
	defer span.End()

View on GitHub (pinned to 329838acdf)

Solutions

Start the daemon with --enable-pubsub-experiment.
Set config: `ipfs config --json PubSub.Enabled true` and restart the daemon.
In library usage, construct the node with the pubsub option/experimental flag enabled.
Check PubSub.Enabled before calling pubsub APIs to fail early with a clearer message.

Example fix

// before
ipfs daemon
// after
ipfs daemon --enable-pubsub-experiment
# or: ipfs config --json PubSub.Enabled true

Defensive patterns

Strategy: fallback

Validate before calling

cfg, err := api.repoConfig() // or read $IPFS_PATH/config
if !cfg.PubSub.Enabled {
	return errors.New("pubsub disabled: set PubSub.Enabled or pass --enable-pubsub-experiment")
}

Type guard

func pubsubAvailable(ps iface.PubSubAPI) bool {
	// Ls on a disabled node fails fast; probe cheaply at startup
	_, err := ps.Ls(context.Background())
	return err == nil || !strings.Contains(err.Error(), "not enabled")
}

Try / catch

err := api.PubSub().Publish(ctx, topic, data)
if err != nil && strings.Contains(err.Error(), "pubsub feature not enabled") {
	return fmt.Errorf("start daemon with --enable-pubsub-experiment: %w", err)
}

Prevention

Enable PubSub.Enabled in config wherever the daemon is provisioned
Probe pubsub availability once at application startup, not per message
Pin the daemon launch flags in your deployment tooling so the experiment is always on

When it happens

Trigger: Calling PubSub().Ls, Peers, Publish, or Subscribe on a CoreAPI from a node started without --enable-pubsub-experiment (or with PubSub.Enabled=false in config), or a node built programmatically without wiring the pubsub service.

Common situations: Developers running `ipfs pubsub pub/sub` against a default-config daemon, embedding kubo as a library and forgetting to enable the experiment, and daemons started by tools that use stock config.

Related errors

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