ipfs/kubo · error

record exceeds maximum size of %d bytes, use --force to skip

Error message

record exceeds maximum size of %d bytes, use --force to skip size check

What it means

Size-limit validation in `ipfs name publish --file`: the supplied raw IPNS record is larger than maxIPNSRecordSize, the maximum allowed by the IPNS record spec. The check runs unless --force is given, protecting nodes from oversized records that peers will reject anyway; --force skips only this size check, not signature validation.

Source

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

		if err != nil {
			return err
		}
		defer file.Close()

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

View on GitHub (pinned to 329838acdf)

Solutions

1. Trim the record's value or V1Signature/V2Signature payload to fit the limit
2. Re-generate the record for a smaller path/value
3. Use --force to publish anyway, accepting that compliant peers may reject the record

When it happens

Trigger: Thrown at core/commands/name/name.go:496 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/2686a55f0b9f8c5a. Report an issue: GitHub.