ipfs/kubo · error

invalid IPNS record: %w

Error message

invalid IPNS record: %w

What it means

Raised by 'ipfs name put' when the provided record bytes cannot be unmarshalled as an IPNS record (ipns.UnmarshalRecord fails): the data is not a well-formed IPNS record (wrong format, corrupt protobuf, or truncated file). Validation only runs without --force.

Source

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

		// Read record data (limit to 1 MiB for memory safety)
		data, err := io.ReadAll(io.LimitReader(file, 1<<20))
		if err != nil {
			return fmt.Errorf("failed to read record: %w", err)
		}
		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()

View on GitHub (pinned to 329838acdf)

Solutions

1. Re-export the record from its source (e.g. 'ipfs name get <name> --record /path') and make sure the file was not truncated or modified in transfer
2. Verify the file actually contains an IPNS record and not a plain CID/path or other content
3. If you intentionally want to store unvalidated bytes, pass --force to skip validation (size check and unmarshal)

When it happens

Trigger: Thrown at core/commands/name/name.go:500 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/340c2b6f8e9b1060. Report an issue: GitHub.