HelloZeroNet/ZeroNet · error · AnnounceError

Announce onion address to failed: %s

Error message

Announce onion address to failed: %s

What it means

After the initial announce, zero trackers may reply with "onion_sign_this" asking the client to prove ownership of its onion address by signing a nonce. The plugin signs with the Tor manager's private key and re-requests announce. If the second response is empty or again contains "onion_sign_this", AnnounceError("Announce onion address to failed: %s") is raised — the onion authentication handshake failed.

Source

Thrown at plugins/AnnounceZero/AnnounceZeroPlugin.py:130

            site_index += 1

        # Check if we need to sign prove the onion addresses
        if "onion_sign_this" in res:
            self.site.log.debug("Signing %s for %s to add %s onions" % (res["onion_sign_this"], tracker_address, len(sites)))
            request["onion_signs"] = {}
            request["onion_sign_this"] = res["onion_sign_this"]
            request["need_num"] = 0
            for site in sites:
                onion = self.site.connection_server.tor_manager.getOnion(site.address)
                publickey = self.site.connection_server.tor_manager.getPublickey(onion)
                if publickey not in request["onion_signs"]:
                    sign = CryptRsa.sign(res["onion_sign_this"].encode("utf8"), self.site.connection_server.tor_manager.getPrivatekey(onion))
                    request["onion_signs"][publickey] = sign
            res = tracker_peer.request("announce", request)
            if not res or "onion_sign_this" in res:
                if full_announce:
                    time_full_announced[tracker_address] = 0
                raise AnnounceError("Announce onion address to failed: %s" % res)

        if full_announce:
            tracker_peer.remove()  # Close connection, we don't need it in next 5 minute

        self.site.log.debug(
            "Tracker announce result: zero://%s (sites: %s, new peers: %s, add: %s, mode: %s) in %.3fs" %
            (tracker_address, site_index, peers_added, add_types, mode, time.time() - s)
        )

        return True

View on GitHub (pinned to 454c0b2e7e)

Solutions

  1. Ensure Tor is running and TorController/control port is configured so getPrivatekey(onion) returns a valid key.
  2. Check the tracker's response in the error for its rejection reason.
  3. Retry — the failed tracker will be full-announced again next cycle.
  4. Disable onion announcement (no onion address) if Tor isn't available.
  5. Update ZeroNet client and tracker to matching protocol versions.

Example fix

// before
sign = CryptRsa.sign(res["onion_sign_this"].encode("utf8"), self.site.connection_server.tor_manager.getPrivatekey(onion))
// after
privatekey = self.site.connection_server.tor_manager.getPrivatekey(onion)
if not privatekey:
    raise AnnounceError("Cannot sign onion challenge: no private key for %s (Tor not available?)" % onion)
sign = CryptRsa.sign(res["onion_sign_this"].encode("utf8"), privatekey)
Defensive patterns

Strategy: try-catch

Validate before calling

if not self.site.connection_server.tor_manager or not self.site.connection_server.tor_manager.getPrivatekey(onion):
    skip_onion_signing = True  # don't attempt onion announce without a key

Type guard

def can_sign_onion(tor_manager, onion):
    return bool(tor_manager and tor_manager.getPrivatekey(onion))

Try / catch

try:
    peers = announce_plugin.announceTrackerZero(tracker_address, file_info, *args)
except AnnounceError as e:
    if "onion" in str(e):
        log.warning("Onion sign challenge failed (Tor available?): %s" % e)
    else:
        raise

Prevention

When it happens

Trigger: Tor manager is unavailable or getPrivatekey(onion) returns None so the sign is missing/invalid; the tracker rejects the RSA signature; the tracker keeps demanding re-signing (nonce/protocol mismatch); the second request times out returning None.

Common situations: ZeroNet running without Tor or without control port access so the onion private key can't be fetched; tracker with onion-signature verification enabled and client's CryptRsa output mismatched; version drift between client and tracker announce protocol.

Related errors

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