ipfs/kubo · error

record validation failed: %w

Error message

record validation failed: %w

What it means

The record unmarshalled fine but ipns.ValidateWithName rejected it against the provided IPNS name: the record's signature does not match the named key, or the record is expired/otherwise invalid per the IPNS spec. Skipped by --force.

Source

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

		if len(data) == 0 {
			return errors.New("record is empty")
		}

		// Validate unless --force
		if !force {
			// Check size limit per IPNS spec
			if len(data) > maxIPNSRecordSize {
				return fmt.Errorf("record exceeds maximum size of %d bytes, use --force to skip size check", maxIPNSRecordSize)
			}
			rec, err := ipns.UnmarshalRecord(data)
			if err != nil {
				return fmt.Errorf("invalid IPNS record: %w", err)
			}

			// 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)
						}
					}
				}
			}

View on GitHub (pinned to 329838acdf)

Solutions

1. Confirm the record was really created by the key matching the --name argument (a record signed by a different key will always fail)
2. Check the record has not expired (records carry a validity window); re-sign or re-export a fresh record if it has
3. Pass --force to store the record without signature validation

When it happens

Trigger: Thrown at core/commands/name/name.go:506 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/46d32b20fa03318d. Report an issue: GitHub.