ipfs/kubo · error

import failed: %w

Error message

import failed: %w

What it means

The fallback message from importError when neither a current nor a previous block is known: `ipfs dag import` failed at the CAR level before any block could be read, so there is no CID context to report.

Source

Thrown at core/commands/dag/import.go:112

		// Default 100MiB. When setting block size to 1MiB, we can add
		// ~100 nodes maximum. With default 256KiB block-size, we will
		// hit the max nodes limit at 32MiB.p
		ipld.MaxSizeBatchOption(int(cfg.Import.BatchMaxSize.WithDefault(config.DefaultBatchMaxSize))),
	)

	roots := cid.NewSet()
	var blockCount, blockBytesCount uint64

	// remember last valid block and provide a meaningful error message
	// when a truncated/mangled CAR is being imported
	importError := func(previous blocks.Block, current blocks.Block, err error) error {
		if current != nil {
			return fmt.Errorf("import failed at block %q: %w", current.Cid(), err)
		}
		if previous != nil {
			return fmt.Errorf("import failed after block %q: %w", previous.Cid(), err)
		}
		return fmt.Errorf("import failed: %w", err)
	}

	it := req.Files.Entries()
	for it.Next() {
		file := files.FileFromEntry(it)
		if file == nil {
			return errors.New("expected a file handle")
		}

		// import blocks
		err = func() error {
			// wrap a defer-closer-scope
			//
			// every single file in it() is already open before we start
			// just close here sooner rather than later for neatness
			// and to surface potential errors writing on closed fifos
			// this won't/can't help with not running out of handles
			defer file.Close()

View on GitHub (pinned to 329838acdf)

Solutions

1. Verify the file is actually a CAR (`ipfs dag stats` won't help; check magic bytes / use `ipfs car ls` if available)
2. Re-download or re-export the CAR
3. Use `ipfs dag put`/`ipfs add` instead if the input was never a CAR

Example fix

// before
ipfs dag import random.bin
// error: import failed: ...
// after
ipfs dag import real-export.car

// check CAR magic bytes before import
f, _ := os.Open(path)
defer f.Close()
hdr := make([]byte, 2)
io.ReadFull(f, hdr) // CARv1/2 start with 0x0a 0xa1 or 0x0a 0xa2 (varint + version)

When it happens

Trigger: CAR whose header is corrupt or unreadable, empty file passed to `ipfs dag import`, or an I/O error reading the very first record.

Common situations: Passing a non-CAR file (e.g. plain UnixFS file or JSON) to `ipfs dag import`; zero-byte file from a failed transfer; CARv1/2 version confusion.

Related errors

• import failed at block %q: %w
• import failed after block %q: %w
• --%s implies --%s=false and cannot be combined with --%s=tru
• expected a file handle

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