ipfs/kubo · error

existing IPNS record has sequence %d >= new record sequence

Error message

existing IPNS record has sequence %d >= new record sequence %d, use 'ipfs name put --force' to skip this check

What it means

Routing already holds a record for this name whose sequence number is greater than or equal to the one being published. Republishing the byte-identical record is allowed (DHT refresh use case); any different record with a non-increasing sequence is rejected to prevent rolling back a name.

Source

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

			// Validate signature against provided name
			err = ipns.ValidateWithName(rec, name)
			if err != nil {
				return fmt.Errorf("record validation failed: %w", err)
			}

			// Check for sequence conflicts with existing record
			existingData, err := api.Routing().Get(req.Context, nameArg)
			if err == nil {
				// Allow republishing the exact same record (common use case:
				// get a third-party record and put it back to refresh DHT)
				if !bytes.Equal(existingData, data) {
					existingRec, parseErr := ipns.UnmarshalRecord(existingData)
					if parseErr == nil {
						existingSeq, seqErr := existingRec.Sequence()
						newSeq, newSeqErr := rec.Sequence()
						if seqErr == nil && newSeqErr == nil && existingSeq >= newSeq {
							return fmt.Errorf("existing IPNS record has sequence %d >= new record sequence %d, use 'ipfs name put --force' to skip this check", existingSeq, newSeq)
						}
					}
				}
			}
			// If Get fails (no existing record), that's fine - proceed with put
		}

		// Publish the original bytes as-is
		// When allowDelegated is true, we set allowOffline to allow the operation
		// even without DHT connectivity (delegated publishers use HTTP)
		opts := []options.RoutingPutOption{
			options.Routing.AllowOffline(allowOffline || allowDelegated),
		}

		err = api.Routing().Put(req.Context, nameArg, data, opts...)
		if err != nil {
			if err.Error() == "can't put while offline" {
				return errPutAllowOffline

View on GitHub (pinned to 329838acdf)

Solutions

1. Publish a record with a higher sequence number (--sequence) so it supersedes the existing one
2. If you are intentionally re-publishing older content (e.g. reverting a name), pass --force to skip the sequence check
3. If you only meant to refresh the DHT entry, publish the exact same record bytes, which is permitted

When it happens

Trigger: Thrown at core/commands/name/name.go:520 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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