config setting IPNS.RecordLifetime (%s) must be >= IPNS.Repu

Error message

config setting IPNS.RecordLifetime (%s) must be >= IPNS.RepublishPeriod (%s), otherwise records expire before they are republished

What it means

Before starting the IPNS republisher, Kubo checks that the record lifetime is at least as long as the republish interval. If records expire sooner than they are republished, published names would silently go stale, so startup fails with this error instead.

Source

Thrown at core/node/ipns.go:65

// IpnsRepublisher runs new IPNS republisher service
func IpnsRepublisher(repubPeriod time.Duration, recordLifetime time.Duration) func(lcStartStop, namesys.NameSystem, repo.Repo, crypto.PrivKey) error {
	return func(lc lcStartStop, namesys namesys.NameSystem, repo repo.Repo, privKey crypto.PrivKey) error {
		repub := republisher.NewRepublisher(namesys, repo.Datastore(), privKey, repo.Keystore())

		if repubPeriod != 0 {
			if !util.Debug && (repubPeriod < time.Minute || repubPeriod > (time.Hour*24)) {
				return fmt.Errorf("config setting IPNS.RepublishPeriod is not between 1min and 1day: %s", repubPeriod)
			}

			repub.Interval = repubPeriod
		}

		if recordLifetime != 0 {
			repub.RecordLifetime = recordLifetime
		}

		if repub.RecordLifetime < repub.Interval {
			return fmt.Errorf("config setting IPNS.RecordLifetime (%s) must be >= IPNS.RepublishPeriod (%s), otherwise records expire before they are republished", repub.RecordLifetime, repub.Interval)
		}

		lc.Append(repub.Run)
		return nil
	}
}

View on GitHub (pinned to 329838acdf)

Solutions

Raise RecordLifetime to be >= RepublishPeriod: `ipfs config Ipns.RecordLifetime 8h` (if RepublishPeriod is 4h)
Or lower RepublishPeriod so it fits under RecordLifetime: `ipfs config Ipns.RepublishPeriod 30m`
Clear one or both settings (`ipfs config --json Ipns.RecordLifetime ""`) to return to defaults where the invariant holds

Example fix

// before (config.json)
"Ipns": { "RepublishPeriod": "4h", "RecordLifetime": "1h" }
// after
"Ipns": { "RepublishPeriod": "4h", "RecordLifetime": "8h" }

Defensive patterns

Strategy: validation

Validate before calling

if recordLifetime != 0 && recordLifetime < repubPeriod {
    return fmt.Errorf("RecordLifetime (%s) must be >= RepublishPeriod (%s)", recordLifetime, repubPeriod)
}

Prevention

Always set RecordLifetime >= RepublishPeriod when overriding either
When changing one IPNS timing option, review both RepublishPeriod and RecordLifetime together

When it happens

Trigger: Configuring IPNS.RecordLifetime shorter than IPNS.RepublishPeriod (e.g. RepublishPeriod=4h, RecordLifetime=1h) and starting the daemon; both values default in and only the explicit combination triggers it.

Common situations: Users setting a short RecordLifetime to "expire names quickly" without realizing it must still exceed the republish interval; mixed defaults where only RecordLifetime was customized while a large RepublishPeriod remained.

Related errors

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