HelloZeroNet/ZeroNet · error · VerifyError

Unable to download piecemap: %s

Error message

Unable to download piecemap: %s

What it means

Bigfile verification splits large files into pieces and relies on a separate '<content>.piecemap.msgpack' file holding the per-piece sha512 hashes. verifyPiece() calls getPiecemap() to fetch that piecemap; if downloading it fails for any reason, the piece cannot be verified and the original error is wrapped in a VerifyError.

Source

Thrown at plugins/Bigfile/BigfilePlugin.py:395

        self.optionalDownloaded(inner_path, hash_id, file_size, own=True)
        self.site.storage.piecefields[hash].frombytes(b"\x01" * piece_num)

        back[file_relative_path] = {"sha512": hash, "size": file_size, "piecemap": piecemap_relative_path, "piece_size": piece_size}
        return back

    def getPiecemap(self, inner_path):
        file_info = self.site.content_manager.getFileInfo(inner_path)
        piecemap_inner_path = helper.getDirname(file_info["content_inner_path"]) + file_info["piecemap"]
        self.site.needFile(piecemap_inner_path, priority=20)
        piecemap = Msgpack.unpack(self.site.storage.open(piecemap_inner_path, "rb").read())[helper.getFilename(inner_path)]
        piecemap["piece_size"] = file_info["piece_size"]
        return piecemap

    def verifyPiece(self, inner_path, pos, piece):
        try:
            piecemap = self.getPiecemap(inner_path)
        except Exception as err:
            raise VerifyError("Unable to download piecemap: %s" % Debug.formatException(err))

        piece_i = int(pos / piecemap["piece_size"])
        if CryptHash.sha512sum(piece, format="digest") != piecemap["sha512_pieces"][piece_i]:
            raise VerifyError("Invalid hash")
        return True

    def verifyFile(self, inner_path, file, ignore_same=True):
        if "|" not in inner_path:
            return super(ContentManagerPlugin, self).verifyFile(inner_path, file, ignore_same)

        inner_path, file_range = inner_path.split("|")
        pos_from, pos_to = map(int, file_range.split("-"))

        return self.verifyPiece(inner_path, pos_from, file)

    def optionalDownloaded(self, inner_path, hash_id, size=None, own=False):
        if "|" in inner_path:
            inner_path, file_range = inner_path.split("|")

View on GitHub (pinned to 454c0b2e7e)

Solutions

  1. Ensure the '<inner_path>.piecemap.msgpack' file exists in the site content.json and is signed/seeded alongside the big file
  2. Check peer connectivity — open the site and let it find peers, or run a seed node, then retry verification
  3. If the piecemap is lost, rebuild it by re-packing the big file (Bigfile pack/build) and update content.json
  4. Read the wrapped cause after 'Unable to download piecemap:' to see the underlying network/error and fix that first
Defensive patterns

Strategy: retry

Validate before calling

# before verification, confirm piecemap is published
piecemap_path = inner_path + '.piecemap.msgpack'
assert piecemap_path in site.content_manager.contents['content.json']['files'], 'piecemap not in content.json'

Try / catch

try:
    site.verifyFile(bigfile_inner_path, f)
except VerifyError as err:
    if 'Unable to download piecemap' in str(err):
        wait_for_peers_and_retry(inner_path)  # exponential backoff
    else:
        raise

Prevention

When it happens

Trigger: verifyFile()/verifyPiece() on a big file whose piecemap file is missing from the site/peers, the tracker/peers are unreachable, or the piecemap download throws (timeout, not found, corrupted).

Common situations: Seeding a big file without uploading the generated .piecemap.msgpack; site opened with no peers online; deleted piecemap after regenerating content; network/firewall blocking peer connections.

Related errors

AI-assisted analysis of HelloZeroNet/ZeroNet@454c0b2e7e (2026-09-02). Data as JSON: /api/errors/82e8340366fd77a1. Report an issue: GitHub.