ipfs/kubo · error · errPutAllowOffline

can't put while offline: pass `--allow-offline` to store loc

Error message

can't put while offline: pass `--allow-offline` to store locally or `--allow-delegated` if Ipns.DelegatedPublishers are set up

What it means

errPutAllowOffline is returned by `ipfs ipns put` when the node is offline and neither --allow-offline nor --allow-delegated was passed. IPNS record publishing normally requires network access to the routing system; this error tells the user which opt-in flag to use for local-only storage or delegated HTTP publishing. Note: at core/commands/name/name.go:538 an older bare "can't put while offline" error is remapped to this richer message.

Source

Thrown at core/commands/name/name.go:340

		if err != nil {
			return err
		}

		res.SetEncodingType(cmds.OctetStream)
		res.SetContentType("application/vnd.ipfs.ipns-record")
		return res.Emit(bytes.NewReader(data))
	},
}

const (
	forceOptionName       = "force"
	putAllowOfflineOption = "allow-offline"
	allowDelegatedOption  = "allow-delegated"
	putQuietOptionName    = "quiet"
	maxIPNSRecordSize     = 10 << 10 // 10 KiB per IPNS spec
)

var errPutAllowOffline = errors.New("can't put while offline: pass `--allow-offline` to store locally or `--allow-delegated` if Ipns.DelegatedPublishers are set up")

var IpnsPutCmd = &cmds.Command{
	Status: cmds.Experimental,
	Helptext: cmds.HelpText{
		Tagline: "Store a pre-signed IPNS record in the routing system.",
		ShortDescription: `
Stores a pre-signed IPNS record in the routing system.

This command accepts a raw IPNS record (protobuf) as defined in the IPNS spec:
https://specs.ipfs.tech/ipns/ipns-record/

The record must be signed by the private key corresponding to the IPNS name.
Use 'ipfs name get' to retrieve records and 'ipfs name inspect' to examine.
`,
		LongDescription: `
Stores a pre-signed IPNS record in the routing system.

This command accepts a raw IPNS record (protobuf) as defined in the IPNS spec:

View on GitHub (pinned to 329838acdf)

Solutions

1. Re-run with --allow-offline to store the record locally only
2. Re-run with --allow-delegated if Ipns.DelegatedPublishers are configured for HTTP publishing
3. Bring the node online (check network/connectivity, routing config) and retry

Example fix

// before
ipfs ipns put --key=self record.bin
// error: can't put while offline: pass `--allow-offline` ...
// after
ipfs ipns put --allow-offline --key=self record.bin

// check offline state / connectivity before publishing
cfg, _ := node.Repo.Config()
// or simply always pass an explicit mode flag in automation

err := ipnsPut(ctx, rec)
if err != nil && strings.Contains(err.Error(), "can't put while offline") {
    // decide: retry with --allow-offline, or wait for connectivity
}

When it happens

Trigger: Running `ipfs ipns put` (or a code path that publishes an IPNS record) while the daemon cannot reach the routing system / network, without --allow-offline or --allow-delegated.

Common situations: Daemon started with Offline mode or in a sandbox/CI without network; publishing a pre-signed record while connectivity is down; tests running against an offline node.

Related errors

• cannot specify negative resolve cache size
• error constructing namesys: %w
• %s : %w
• this action must be run in online mode, try running 'ipfs da
• Name.Resolve: depth other than 1 or %d not supported

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