For people who run a tracker. Each problem below starts in plain words, with things to try that don't need the command line, and what to ask your hosting provider if someone else runs the server for you. If you're comfortable with a terminal, open For advanced users in each section for exact commands.
Hands out no peers Returns fake peers IPv4 or IPv6 broken Dead DNS record (Up/Broken) Drops out (Up/Unreliable, Up/Junk) Slow (Up/Slow) Down: timeout Down: connection refused Down: DNS Down: TLS / certificate Down: HTTP error Down: the tracker rejects requests Down: no usable answer Announce interval too short or too long Refuses torrents whose info hash contains "&" Removed and banned Separate servers that don't share swarms (Up/Broken) Down from New Zealand only (answers elsewhere) Hands out an address nobody can reach
Not sure what your tracker runs on? Most public trackers are opentracker, Chihaya, Torrust or Aquatic on a rented server (a VPS). If a friend or a company set it up, send them the link to the section below that matches your problem: it's written so they can act on it.
The advanced examples use tracker.example.org and port 6969: put in your own.
In plain words: your tracker answers, but it doesn't do its actual job: introducing people who share the same torrent to each other. Torrent clients that use it don't find anyone through it.
How we know: two test clients in different countries join the same made-up torrent. The second should be told about the first. Yours left the first one out in 3 or more of the last 6 tests.
Most likely causes, and what to do:
If the tracker sends a message with its answers, such as "Require passkey" or "info hash is not authorized", it's shown on its page under Message from the tracker, with what it means. Those two mean it's private or only serves its own torrents: that's a choice, not a fault, but it can't work as a public tracker.
Ask your provider or admin: "Our tracker answers but doesn't share peers between clients (newtrackon.co.nz reports Up/Bad: no peers). Can you check it accepts any torrent, mixes IPv4 and IPv6 peers in one swarm, and sees clients' real IP addresses?"
Announce the same torrent twice with different ports. The second reply should list the first peer (6881).
A failure reason such as "torrent not registered" means it's whitelisted.
H='%12%34%56%78%9a%bc%de%f0%12%34%56%78%9a%bc%de%f0%12%34%56%78' U='http://tracker.example.org:6969/announce' curl -s "$U?info_hash=$H&peer_id=-NT0001-000000000001&port=6881&uploaded=0&downloaded=0&left=0&compact=0"; echo curl -s "$U?info_hash=$H&peer_id=-NT0001-000000000002&port=6882&uploaded=0&downloaded=0&left=0&compact=0"; echo
Fix: allow unknown torrents (for opentracker: build without the whitelist option), and hand out peers from the same swarm
regardless of the address family they announced from. If it's behind a reverse proxy, pass the client address through
(for example X-Forwarded-For, and configure the tracker to trust it). The status clears after a few passing tests.
In plain words: your tracker hands out addresses of "people" who aren't really sharing the torrent. Clients waste time trying to connect to them, and downloads look busier than they are.
How we know: the test torrent is made up and only this site knows it, so the only real users are our own test clients. Yours returned other addresses for it, 3 or more checks in a row.
Most likely causes, and what to do:
Ask your provider or admin: "newtrackon.co.nz reports our tracker returns peers for a torrent nobody else has. Can you turn off any peer padding or caching of announce replies, and make sure peers expire?"
Announce a torrent nobody has (the first command under Hands out no peers, with a hash you make up). The reply should have no peers except, at most, yourself.
Fix: turn off any "fill" or "padding" option, keep peer lists per torrent, expire peers that stop announcing, and don't cache
announce replies (Cache-Control: no-store on the announce path). The status clears as soon as a check sees only real peers.
In plain words: your tracker's name points to two kinds of address: an older one (IPv4) and a newer one (IPv6). One of them works and the other doesn't. People whose computer picks the broken one can't reach your tracker at all.
How we know: we check both addresses separately. One answers; the other has failed several checks in a row.
Or: one of several addresses is dead. Your tracker's name has more than one address of the same kind (two A records, say) and every check we ask each of them. One has failed 3+ times in a row while the others answer. A client picks one at random, so some clients can't reach your tracker at all. The tracker's page lists the dead address: delete its record, or make it answer.
Or: one family doesn't share peers. Both addresses answer, but clients on one of them (often IPv6) are never
told about each other: our two test clients on IPv6 never meet, while on IPv4 they do. Usual causes: the tracker keeps no
peer lists for that family (an IPv4-only build answering on IPv6), or something in front of it hides IPv6 clients' real
addresses. The tracker's page says which family, and if it hands out an address nobody can reach (like
172.17.0.1 or 127.0.0.1), that's the cause: see
Hands out an address nobody can reach.
Most likely causes, and what to do:
The tracker's page says which one is dead. If you don't need IPv6, deleting the AAAA record is a quick, complete fix.
Ask your provider or admin: "Our tracker answers on IPv4 but not IPv6 (or the other way round). Can you check the DNS records point at the server's current addresses, and that the tracker listens and the firewall is open on both?"
List the addresses, then try each family.
dig +short A tracker.example.org; dig +short AAAA tracker.example.org
curl -4 -s -m 5 -o /dev/null -w '%{http_code}\n' http://tracker.example.org:6969/announce # HTTP tracker, IPv4
curl -6 -s -m 5 -o /dev/null -w '%{http_code}\n' http://tracker.example.org:6969/announce # HTTP tracker, IPv6
For a UDP tracker, this sends the standard UDP tracker "connect" request (BEP 15) over IPv4 or IPv6 (the last argument):
python3 - tracker.example.org 6969 6 <<'EOF'
import os, socket, struct, sys
host, port, fam = sys.argv[1], int(sys.argv[2]), sys.argv[3]
af = socket.AF_INET6 if fam == "6" else socket.AF_INET
addr = socket.getaddrinfo(host, port, af, socket.SOCK_DGRAM)[0][4]
s = socket.socket(af, socket.SOCK_DGRAM); s.settimeout(5)
tid = os.urandom(4)
s.sendto(struct.pack(">QI4s", 0x41727101980, 0, tid), addr)
try:
print(addr[0], "answered" if s.recv(16)[4:8] == tid else "answered something unexpected")
except OSError as e:
print(addr[0], "no answer:", e)
EOF
A tracker that stays Up/Broken (or Up/Junk) for 30 days is removed: deleting the dead record takes a minute.
Fix: make the tracker listen on both families (for example bind :: as well as 0.0.0.0) and open the
port for both in the firewall (ip6tables/nft rules are separate from IPv4 ones), or remove the record for
the family you don't serve. It clears once that address answers.
In plain words: your tracker's name lists an address that nothing answers on. It's like a business card with an old phone number on it next to the right one: everyone who rings the old number gets nowhere, even though you're there.
How we know: every check asks each address the name gives, one by one. This address has failed 3 or more checks in a row while the tracker's other address (or its other IP family) answers every time. The tracker's page names the dead address.
Why it matters: a torrent client looks up the name and picks one of the addresses. Clients that pick the dead one can't reach your tracker at all, so a share of your users loses the tracker for good, and they can't tell why.
Most likely causes, and what to do:
Deleting the dead record is usually the whole fix. It takes a minute, and the warning clears once checks stop seeing that address (DNS changes can take a few hours to reach everyone). A tracker that stays Up/Broken for 30 days is removed.
Ask your provider or admin: "Our tracker's name has a DNS record for an address that doesn't answer. Can you delete that record, or point it at the server's current address?"
List every address the name gives, then try each one directly (the UDP command under IPv4 or IPv6 broken works too, with an address instead of the name):
dig +short A tracker.example.org; dig +short AAAA tracker.example.org
for ip in $(dig +short A tracker.example.org); do
curl -s -m 5 -o /dev/null -w "$ip %{http_code}\n" --resolve tracker.example.org:6969:$ip http://tracker.example.org:6969/announce
done
In plain words: your tracker shares peers, but it gives everyone the wrong address for each peer, so nobody can connect to anyone it hands out. It doesn't see where clients really come from: something between them and the tracker puts its own address in their place.
How we know: our second test client is handed our first one, but with an address that isn't ours. The tracker's page shows the address it gave out.
Hands out 127.0.0.1 (or ::1). Every connection reaches the tracker from its own machine: a reverse proxy
(nginx, Caddy, a NAS's built-in reverse proxy), a port forward or a tunnel on the same machine passes it on without the
client's address. Either connect clients straight to the tracker's own port, or make the tracker take the client's
address from the header the proxy adds (X-Forwarded-For or X-Real-IP; in opentracker,
Chihaya and most others it's a setting, often called "real IP header"), and only from the proxy itself. A UDP tracker
can't sit behind an HTTP proxy at all: it needs its port open directly.
Hands out 172.17.0.1 (or another 172.16 to 172.31 address). The tracker almost always runs in Docker
and IPv6 (or all) traffic reaches it through Docker's port proxy, which replaces each client's address with the
container's gateway. Fix: give the container real IPv6 (in /etc/docker/daemon.json set
"ipv6": true, "ip6tables": true and an IPv6 subnet, or run it with
network_mode: host), or set the tracker to trust the real client address from whatever sits in front of it.
Hands out another private address (10.x, 192.168.x). A router, firewall or load balancer in front of it translates addresses (NAT) on the way in, so every client arrives from that box. Forward the port to the tracker without rewriting the source address, or have the load balancer pass the client's address on.
Hands out a proxy's or CDN's address. The same fault behind a reverse proxy or a CDN such as Cloudflare: the
tracker sees the proxy's address for everyone. Make the tracker take the client's address from the header the proxy
adds (CF-Connecting-IP or X-Forwarded-For; in opentracker, Chihaya and most others it's a
setting, often called "real IP header"), and only from your proxy's addresses. Cloudflare doesn't carry UDP, so a UDP
tracker behind it can't work at all.
Hands out 0.0.0.0, 255.255.255.255 or ::. Nothing sits in front of it: the tracker program itself
doesn't keep clients' real addresses and fills in a placeholder. It's most often IPv6 clients, with a tracker build or
setting that can't store IPv6 addresses. Update the tracker program, turn on its IPv6 support, or stop it answering
on IPv6 (remove the AAAA record) if it can't serve IPv6 clients properly.
Then press Check again now on its page.
In plain words: your tracker is really several tracker servers behind one name, and they don't tell each other who is in each torrent. Two people only find each other if they happen to reach the same server, so most of the time they don't. It still works for some, so it stays listed as Up/Broken.
How we know: our second test client is sometimes handed back only itself, by a server that has never seen our first client, which announced seconds earlier. Other times the two land on the same server and meet normally.
Most likely causes, and what to do:
hash $arg_info_hash consistent; in the upstream block); for
UDP the info-hash is inside the packet, so it needs the tracker's own clustering support.The tracker's page shows how many of our peer tests met a different server.
Ask your provider or admin: "Our tracker runs on several servers behind one name, and they don't share peer lists, so clients often don't find each other. Can all instances use shared storage, or can we run just one?"
A tracker that stays Up/Broken (or Up/Junk) for 30 days in a row is removed.
In plain words: your tracker works some of the time, but too often it doesn't answer. Users can't rely on it, so it's marked down the list. Lots of short dropouts count against it more than one longer outage.
How we know: its score, which counts the last week most, is under 90 (Up/Unreliable) or under 50 (Up/Junk). The uptime bars on its page show when it drops out.
Most likely causes, and what to do:
Once it's steady, the score climbs back by itself over about a week. There's nothing to reset. A tracker that stays Up/Junk (score under 50) for 30 days is removed: a month is long enough for any temporary overload to pass.
Ask your provider or admin: "Our tracker keeps dropping out (newtrackon.co.nz shows Up/Unreliable). Can you check the logs for crashes, restarts or running out of memory, make sure it restarts automatically, and that rate limits aren't rejecting normal announces?"
Run it under a supervisor that restarts it (systemd Restart=always, Docker restart: unless-stopped), check
journalctl or the container logs and dmesg for OOM kills around the drop times, don't rate-limit announces so
hard that real requests fail, and give it a fixed address. A UDP tracker needs enough socket buffer for bursts
(net.core.rmem_max).
Limiting abusive clients. First find out whether a few addresses really cause the load
(tcpdump -nn -c 20000 udp port 6969 | awk '{print $3}' | sed 's/\.[0-9]*$//' | sort | uniq -c | sort -rn | head,
or count lines per address in an HTTP tracker's access log). Then:
UDP tracker: a per-address rate limit in the firewall (nftables). It drops only the excess above the limit, and
forgets an address 2 minutes after it calms down. Don't use long bans for UDP: a UDP sender's address can be forged, so an
attacker could get innocent addresses banned. Load it with nft -f /etc/nftables.d/tracker.nft (and include it
from /etc/nftables.conf to keep it after a reboot); nft list set inet tracker_limit rate4 shows
who's being limited.
# /etc/nftables.d/tracker.nft: per-address rate limit for a UDP tracker on port 6969
table inet tracker_limit {
set rate4 { type ipv4_addr; flags dynamic, timeout; timeout 2m; }
set rate6 { type ipv6_addr; flags dynamic, timeout; timeout 2m; }
chain input {
type filter hook input priority filter - 5; policy accept;
# over 20 packets/s (bursts of 60 allowed) from one address: drop the excess
udp dport 6969 update @rate4 { ip saddr limit rate over 20/second burst 60 packets } counter drop
udp dport 6969 update @rate6 { ip6 saddr limit rate over 20/second burst 60 packets } counter drop
}
}
HTTP tracker: fail2ban on the web server's access log. TCP addresses can't be forged, so a timed ban is safe here.
This bans an address for an hour after 300 announces or scrapes in a minute. Test the filter first with
fail2ban-regex /var/log/nginx/access.log /etc/fail2ban/filter.d/tracker-flood.conf, then
fail2ban-client reload; fail2ban-client status tracker-flood lists the bans.
# /etc/fail2ban/filter.d/tracker-flood.conf: every announce or scrape in an nginx/Apache access log [Definition] failregex = ^<HOST> \S+ \S+ \[\] "GET /(?:announce|scrape)\b ignoreregex =
# /etc/fail2ban/jail.d/tracker-flood.local: ban addresses announcing absurdly often (HTTP trackers only) [tracker-flood] enabled = true port = http,https filter = tracker-flood logpath = /var/log/nginx/access.log # 300 announces in 60 s from one address = 5 a second, sustained. A normal client announces every # 30 minutes or so, so even hundreds of users behind one shared (CGNAT) address stay far below this. findtime = 60 maxretry = 300 bantime = 1h
Both thresholds are deliberately high; lower them only if you can see abuse slipping under them. If many different addresses each send a little (a real distributed flood), per-address limits won't help: that needs your hosting provider's DDoS protection.
In plain words: your tracker works and is reliable, but answers slowly for most of the world. It's still listed and usable; it just isn't among the fastest.
How we know: answers take 300 ms or more on average from the four places speed is measured (Oceania, Asia, Europe, North America), or enough to pull its score under 90.
This isn't a fault, and often it's simply distance: a tracker in one country is slow from the other side of the world. The latency chart on its page shows each region. If it's slow from everywhere, including nearby: the server may be overloaded, or there's a slow service in front of it (some protection or proxy services add a lot of delay to HTTP trackers).
Check the server's load and network, avoid chains of proxies in front of an HTTP tracker, and prefer UDP (much less overhead per announce). Hosting closer to most users helps most.
In plain words: your tracker works for people in other countries, but this site's server in New Zealand gets no answer from it. It stays listed, shown as Down from NZ, and it's tested from our test clients in other countries instead (peer test included), so it's judged like every other tracker.
How we know: our checks from New Zealand time out or are refused, while our test clients in other countries get answers.
Most likely causes:
In plain words: we knocked and nobody answered at all. Either the tracker isn't running, or something is silently blocking the way to it.
How we know: no reply within the time limit, from here and from abroad.
Things to try:
Ask your provider or admin: "Our tracker at port 6969 (UDP) doesn't answer from outside. Is the server up, is the tracker process running, and is UDP 6969 open in every firewall in front of it?"
From a machine outside your network, run the UDP command under Dead IPv4 or IPv6 address, or the
curl command for HTTP. On the server, ss -lunp | grep 6969 (UDP) or ss -ltnp | grep 6969 (TCP)
shows whether it's listening, and nft list ruleset or iptables -S shows the firewall.
In plain words: the server is up, but it said "there's nothing here" on the tracker's port. The tracker program isn't running, or it's listening somewhere else.
How we know: the server actively refused the connection.
Things to try:
:6969) must be
the one the program uses. If you changed it, update the address you've shared, or submit the new one.127.0.0.1 can't be reached from outside.Ask your provider or admin: "Connections to our tracker's port are refused. Is the tracker running, on that port, and listening on the public address?"
Start it and make it listen on the public address and the port in your announce URL (ss -lunp / ss -ltnp
shows what's listening where). If you moved it to a new port, you can publish that with a
BEP 34 DNS record.
In plain words: your tracker's name doesn't lead anywhere any more. It's like a phone number that's been disconnected: nobody can find the server, even if it's running fine.
How we know: the name has no address, both here and on public DNS services.
Things to try:
After a fix, DNS changes can take up to a few hours to reach everyone.
dig +short A tracker.example.org @1.1.1.1 and whois example.org for the expiry date and nameservers.
dig +trace tracker.example.org shows where resolution breaks.
In plain words: your tracker's address starts with https://, and its security certificate (the thing behind
the padlock in a browser) isn't valid, so clients refuse to connect.
How we know: the secure connection failed.
Things to try:
example.org but not
tracker.example.org). Add the tracker's name to the certificate.If you'd rather not deal with certificates, a plain http:// or udp:// address works just as well for a tracker.
openssl s_client -connect tracker.example.org:443 -servername tracker.example.org </dev/null | openssl x509 -noout -dates -subject
shows the dates and name. A missing intermediate certificate also fails here: serve the full chain (fullchain.pem).
In plain words: a web server answered, but with an error message instead of a tracker answer. It's like reaching reception, being told "not here", and never getting to the person you called.
How we know: the reply was an error code: 4xx (refused or not found) or 5xx (the server behind it failed).
What the error usually means:
/announce)./announce to the tracker program.Ask your provider or admin: "Our tracker's /announce returns an HTTP error (the code is on the newtrackon.co.nz page). Can you check the web server passes /announce to the tracker, that the tracker is running, and that bot protection doesn't apply to it?"
Run the curl command under Hands out no peers and read the status and body. Torrent clients can't
pass a browser challenge, so turn it off for the announce path, and check the reverse proxy's location for
/announce and its upstream.
In plain words: your tracker is running and answers, but every answer is an error message of its own ("invalid info_hash", "incorrect request", "torrent not allowed" and so on) instead of a list of peers. To a torrent client it's as good as down.
How we know: the tracker's own error text is on its page, under What's wrong. We send standard, valid requests.
What the message usually means:
Ask your provider or admin: "Our tracker answers announces with an error (the message is on the newtrackon.co.nz page). Can you check the tracker software is up to date and that nothing in front of it alters the request?"
Run the curl command under Hands out no peers: the bencoded failure reason is the
message. For a UDP tracker, the reply is action 3 with the message after the 8-byte header (BEP 15).
If info_hash errors only happen for some hashes, look for something decoding %00, %2B or
non-UTF-8 bytes in the query string (a reverse proxy normalising URLs, or a framework parsing the query as text).
In plain words: something answered, but not like a tracker, or it failed in a way not covered above.
How we know: the exact error is on the tracker's page.
Try the basics: restart the tracker program, make sure the address you've shared (protocol, name, port and the /announce
part) matches what it actually runs, and that it's a public tracker (one that needs an account or passkey can't be listed).
If the error on the tracker's page mentions a timeout, refusal, DNS, certificate or HTTP code, see that section above.
The checks above (listening, firewall, the curl or UDP command) usually find it. A UDP tracker that replies to
connect but not announce, or an HTTP tracker that returns non-bencoded data, shows up here.
In plain words: every answer tells torrent clients how long to wait before asking again (the interval). Yours asks for far too often (some trackers say every 2 minutes) or far too rarely (some say once a day).
How we know: it's in every answer your tracker sends. The tracker's page shows it under Details, and the points it costs in the score breakdown.
Why it matters:
What to do: set it to about 30 minutes (1800 seconds), with a min interval of about 15 minutes. That's what almost every public tracker uses. The points only affect the score and ranking: they don't change the status, and the tracker stays listed. The score updates at the next check after you change it.
Ask your provider or admin: "Can you set our tracker's announce interval to 30 minutes (1800 s) and its min interval to 15 minutes (900 s)?"
[core.announce_policy] with interval = 1800 and
interval_min = 900. Its default is 120 for both, which is why many Torrust trackers ask for 2 minutes.announce_interval: "30m" and min_announce_interval: "15m" (the defaults).OT_CLIENT_REQUEST_INTERVAL in trackerlogic.h, set when it's built
(default 60 * 30, 30 minutes).peer_announce_interval in the [protocol] section, in seconds (default 900).In plain words: your tracker turns away about 1 in 13 torrents (7.5%) with an “invalid info_hash” error. It works for all the others, so it stays listed, but it's left out of the clean lists until it's fixed.
How we know: once a day we announce a random torrent whose info hash contains the byte 0x26, the
“&” character. Every client sends that byte as %26 in the announce URL, as the
BitTorrent spec says. Your tracker answers our normal announces, but refuses that one.
Why it happens: the tracker decodes the whole query string (turning %26 back into
&) and only then splits it into parameters at each &. The info hash is then cut short at
that byte, so it's shorter than 20 bytes and gets refused. Any torrent whose hash holds that byte, about 7.5% of them, can't
use the tracker at all.
What to do: split the query string at each & first, then percent-decode each name and value on its
own. Most web frameworks' query parsers already do it in that order: the bug is usually hand-written parsing, or decoding
the URL before passing it on. The warning clears at the next daily test after it's fixed.
Ask your provider or admin: "Our tracker refuses info hashes that contain the byte 0x26 (sent as %26). Can you make it split the announce query on & before percent-decoding the values?"
Announce with an info hash holding 0x26 and compare with one that doesn't, for example (20 bytes each, the first has
%26 in it):
curl '<announce URL>?info_hash=%26AAAAAAAAAAAAAAAAAAA&peer_id=-qB5050-000000000000&port=6881&uploaded=0&downloaded=0&left=0&compact=1&event=stopped' curl '<announce URL>?info_hash=BAAAAAAAAAAAAAAAAAAA&peer_id=-qB5050-000000000000&port=6881&uploaded=0&downloaded=0&left=0&compact=1&event=stopped'
A fixed tracker answers both the same way. A broken one says “invalid info_hash” (often with a length under 40 hex characters) for the first.
In plain words: your tracker was taken off the list because it stopped working, or never worked as a public tracker, for too long. For a while it can't be submitted again.
How we know: its page (the same address as before) says when and why it was removed, and when the ban ends.
A tracker is removed when:
It's then banned: for 30 days the first time, 90 days the second, and for good after that. Submitting it again is refused until the ban ends. A tracker turns dark grey in the status table once it's 2 days from removal (Down or Up/Bad for 3 days), so there's still time to fix it. See the banned trackers.
What to do: fix the problem (the sections above), then press Check again now on the tracker's page. It's checked like a new submission: if it answers properly (twice, 30 minutes apart), it's listed again and the ban is lifted, even before the ban ends. If the ban is permanent, it can't come back.
The removal reason, ban end and removal count are also in /api/tracker/<host> (a 404 with a
removed object) and in /api/removed. A tracker removed for Up/Bad keeps its 5-day count when it's
reinstated, and a reinstated tracker gets back its last week of uptime, so a fix has to be real to stick.
Questions: see the FAQ.