What causes "failed to read record: %w" in ipfs/kubo?

Verify the record file is a readable regular file and retry

failed to read record: %w

Error message

failed to read record: %w

What it means

Returned when reading the raw IPNS record bytes (from the file/stdin argument, capped at 1 MiB via io.LimitReader) fails. The wrapped error is the underlying read I/O failure. (An empty record is rejected separately right after.)

Source

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

		}
		// Extract the name part after /ipns/
		namePart := strings.TrimPrefix(nameArg, "/ipns/")
		name, err := ipns.NameFromString(namePart)
		if err != nil {
			return fmt.Errorf("invalid IPNS name: %w", err)
		}

		// Read raw record bytes from file/stdin
		file, err := cmdenv.GetFileArg(req.Files.Entries())
		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)

View on GitHub (pinned to 329838acdf)

Solutions

Verify the record file is a readable regular file and retry
If piping, ensure the producing command (e.g. ipns sign/presign tool) exits successfully
Regenerate the record file if it is on flaky storage

Example fix

// before
some-producer | ipfs ipns put --allow-offline --key=self
// error: failed to read record: read |0: file already closed
// after
some-producer > record.bin && ipfs ipns put --allow-offline --key=self record.bin

Defensive patterns

Strategy: try-catch

Validate before calling

fi, err := os.Stat(recordFile)
if err != nil || !fi.Mode().IsRegular() || fi.Size() == 0 || fi.Size() > 1<<20 {
    return errors.New("record file must be a non-empty regular file under 1 MiB")
}

Try / catch

data, err := io.ReadAll(io.LimitReader(f, 1<<20))
if err != nil {
    return fmt.Errorf("failed to read record: %w", err)
}

Prevention

Write records to a temp file before publishing instead of long pipe chains
Check producer exit status before consuming its output

When it happens

Trigger: `ipfs ipns put <name> <file>` where the record file cannot be read mid-stream — I/O error on the device, pipe producer failure while reading stdin.

Common situations: Piping record data from a process that dies mid-write, reading from an unreadable/special file, or storage errors on the record file.

Understand the failure class

Background: "failed to read file", EACCES, ENOENT and "could not read <path>" errors: when a program can't read a file from disk — this error's family across 49 libraries.

Related errors

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