ipfs/kubo · error · ErrOffline

this action must be run in online mode, try running 'ipfs…

Error message

this action must be run in online mode, try running 'ipfs daemon' first

What it means

`iface.ErrOffline` is a sentinel error returned when an operation requires network connectivity but the node is running offline (no daemon or daemon with libp2p disabled). IPNS publishing, routing put, swarm connect/disconnect, and path resolution against DNS/IPNS all need online mode, so CoreAPI implementations return this sentinel so callers can map it to a friendlier message (kubo's CLI converts it to errAllowOffline when --offline semantics allow).

Solutions

1. Start the daemon (`ipfs daemon`) so the node is online, then retry the operation.
2. If the operation is intentionally offline (e.g. IPNS publish with an offline private key), use the offline-capable path: `ipfs name publish --offline` (kubo maps ErrOffline to errAllowOffline for commands that support it).
3. In code, detect it with `errors.Is(err, iface.ErrOffline)` and either surface the 'run ipfs daemon first' hint or fall back to an offline variant of the operation.

Example fix

// before
name, err := api.Name().Publish(ctx, p)
if err != nil { return err }
// after
name, err := api.Name().Publish(ctx, p)
if err != nil {
    if errors.Is(err, iface.ErrOffline) {
        return cmdErrAllowOffline // or prompt user to start daemon
    }
    return err
}

// Before IPNS publish / routing put, confirm the node is online:
// 1) an ipfs daemon is running and API reachable: `ipfs id`
// 2) Routing.Type is not 'none' for routing operations

err := api.Name().Publish(ctx, p)
if err != nil {
    if errors.Is(err, iface.ErrOffline) {
        // either start the daemon or take the offline-capable path
        return publishOffline(ctx, p) // e.g. `ipfs name publish --offline`
    }
    return err
}

When it happens

Trigger: Calling `api.Name().Publish`, `api.Routing().Put`, `api.Swarm().Connect/Disconnect`, `api.Swarm().KnownAddrs`, or `api.Name().Resolve` while the node is offline: either no `ipfs daemon` is running (offline CLI commands like `ipfs name publish` without a daemon) or the daemon runs with routing disabled/no libp2p host.

Common situations: Running `ipfs name publish` without a daemon (users often hit this and need `--offline` or must start the daemon); scripts that assumed a local API was online but the daemon crashed; nodes configured with `Routing.Type=none` trying routing operations; CI environments that forgot to start the daemon.

Related errors

• api not running
• can't put while offline: pass `--allow-offline` to store…
• cannot specify negative resolve cache size
• could not resolve name
• error constructing namesys

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

Appendix: source

Thrown at core/coreiface/errors.go:8

package iface

import "errors"

var (
	ErrIsDir        = errors.New("this dag node is a directory")
	ErrNotFile      = errors.New("this dag node is not a regular file")
	ErrOffline      = errors.New("this action must be run in online mode, try running 'ipfs daemon' first")
	ErrNotSupported = errors.New("operation not supported")
)

View on GitHub (pinned to 329838acdf)