ipfs/kubo · error

import failed at block %q: %w

Error message

import failed at block %q: %w

What it means

When `ipfs dag import` fails while reading/validating a block from a CAR, kubo wraps the underlying error with the CID of the block that could not be imported, giving a meaningful message for truncated or mangled CARs. The wrapper is `import failed at block %q: %w` when the current (failing) block is known.

Source

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

	// it is simply a way to relieve pressure on the blockstore
	// similar to pinner.Pin/pinner.Flush
	batch := ipld.NewBatch(req.Context, api.Dag(),
		// Default: 128. Means 128 file descriptors needed in flatfs
		ipld.MaxNodesBatchOption(int(cfg.Import.BatchMaxNodes.WithDefault(config.DefaultBatchMaxNodes))),
		// 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
			//

View on GitHub (pinned to 329838acdf)

Solutions

1. Re-download or re-export the CAR file; the copy is corrupt
2. Verify with `ipfs dag export <root> > fresh.car` and compare, or use a CAR verifier
3. Import with --stats to see how far the import progressed before failing
4. Use `ipfs car verify` (from go-car tooling) to locate all bad blocks

// sanity-check CAR before import
st, err := os.Stat(carPath)
if err != nil || st.Size() == 0 {
    return fmt.Errorf("CAR missing or empty: %s", carPath)
}
// optionally verify hashes with go-car before importing

// catch and surface the offending CID
if err := run("ipfs", "dag", "import", car); err != nil {
    var cidStr string
    if m := reBadBlock.FindStringSubmatch(errText(err)); m != nil {
        cidStr = m[1] // re-export or re-download around this block
    }
    return fmt.Errorf("car corrupt at %s: %w", cidStr, err)
}

When it happens

Trigger: CAR file whose block bytes are corrupt, truncated mid-block, hash-mismatched, or unreadable during `ipfs dag import`; the failing block was successfully read enough to know its CID.

Common situations: Interrupted downloads producing truncated CARs; CARs modified in transit; bad blockstore writes from previous failed runs; CARv2 files read incorrectly.

Related errors

• import failed after block %q: %w
• import failed: %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/1466ebebdaa0e4e1. Report an issue: GitHub.