ipfs/kubo · error · ErrOffline

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

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).

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)

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

• 'ipfs id' cannot query information on remote peers without a
• can't put while offline: pass `--allow-offline` to store loc
• cannot specify negative resolve cache size
• error constructing namesys: %w
• %s : %w

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