Tech Digest

Guide

Pi-hole "Client has been rate-limited (current config allows up to 1000 queries in 60 seconds)"

Because Pi-hole counts queries per sending address, and a router that forwards for the whole house is one address. We flooded Pi-hole v6 from one client, recorded what it got back and for how long, and read the rule in FTL's source.

Last reviewed

Why does Pi-hole say a client has been rate-limited, and how do you fix it?

The client sent more than 1,000 queries inside one 60-second window, so Pi-hole answers it with REFUSED until the window ends. When that client is your router, it is forwarding for every device in the house, so they all share one quota. The real fix is to have DHCP, and IPv6 router advertisements, hand out Pi-hole's address directly. If you cannot, raise dns.rateLimit.count (Settings > DNS, expert mode, or FTLCONF_dns_rateLimit_count). Set it to 0 to switch limiting off. Never set only the interval to 0.

One address sent Pi-hole more than 1,000 DNS queries inside one 60-second window, so Pi-hole is refusing to answer it until the window ends. If that address is your router, the router is forwarding for every phone, laptop and TV in the house. To Pi-hole they are all one client, and they share one quota.

The fix is to stop the router being in the middle. Have its DHCP server, and its IPv6 router advertisements, hand out Pi-hole's address as the DNS server. Each device then talks to Pi-hole itself and gets its own 1,000. If the router will not let you, raise the limit instead:

toml
# /etc/pihole/pihole.toml
[dns.rateLimit]
  count = 4000
  interval = 60

In Docker, set FTLCONF_dns_rateLimit_count: 4000 in the environment. In the web interface it is under Settings > DNS, in expert mode, in the box called Rate-limiting.

The terms this answer turns on#

Rate limiting here means a cap on how many DNS queries Pi-hole will answer from one source in a set time. FTL, the program at the heart of Pi-hole, keeps one counter per client. The docs say it plainly: "rate-limiting is happening on a per-client basis."

A client, to Pi-hole, is the IP address a query arrives from. It is not a person or a device. If ten devices ask your router and the router asks Pi-hole, Pi-hole sees one client: the router.

REFUSED is a standard DNS answer code. It means "I will not answer this." The docs say rate-limited queries "are answered with a REFUSED reply and not further processed by FTL."

DHCP is how devices get their network settings when they join. One of those settings is which DNS server to use. On IPv6, a router can also announce a DNS server in its router advertisements, the messages it sends so devices can set themselves up. Either one can point devices at the router instead of at Pi-hole.

You searched the v5 wording#

The exact text in the search box comes from Pi-hole v5's web interface. Its messages.js builds "has been rate-limited (current config allows up to 1000 queries in 60 seconds)". Pi-hole v6 words it differently. FTL v6.9 writes this to /var/log/pihole/FTL.log:

text
INFO: Rate-limiting 10.253.53.10 for at least 13 seconds

The v6 web interface shows: "Client 10.253.53.10 has been rate-limited for at least 13 seconds (current limit: 1000 queries per 60 seconds)." The cause and the fix are the same on both. Only the setting moved. In v5 it was RATE_LIMIT=1000/60 in pihole-FTL.conf. In v6 it is two keys, and FTL copies an old RATE_LIMIT line across when it migrates a v5 install.

Why the client is so often your router#

In the forum thread most people land on, the limited client was 192.168.1.254, the poster's router. A Pi-hole moderator named the usual reason. Rate limiting is likely "in configurations where clients use the router for DNS while the router is using Pi-hole as its upstream, aggregating DNS requests for the entire network." The second cause they named is conditional forwarding pointed at a router that itself uses Pi-hole, which can close "a partial DNS loop". They called these "the two most common causes".

1,000 queries a minute is about 17 a second. Behind a forwarding router, every phone, TV and laptop in the house counts toward that one number.

That thread had a twist. Pi-hole was already the DHCP server and handed out its own IPv4 address. The leak was IPv6. The Pi-hole host had picked up two IPv6 DNS servers, and the moderator judged it "highly likely" that one was the router "advertising its own IPv6 address as DNS server". That let devices "by-pass Pi-hole by using your router instead". The router then forwarded those queries to Pi-hole, all under its own address. The poster found an iPhone that kept an extra IPv6 DNS server "which came back every time". After they turned IPv6 off on the FRITZ!Box, they reported that the router's rate-limit warning "seemed to" have gone.

What a limited client gets#

We ran pihole/pihole with FTL v6.9, Web v6.6.1 and Core v6.6, all defaults except a test record. Clients ran dnsperf and dig from their own fixed addresses. A dnsmasq 2.91 container played the router, forwarding to Pi-hole with its cache off so every query reached Pi-hole.

From one client, we sent 1,100 queries in about a second. The first ones were answered, then the rest got REFUSED:

What we didWhat came back
1,100 queries in about a secondAnswered up to the limit, then REFUSED for the rest
dig from the same client straight afterstatus: REFUSED, ANSWER: 0, in milliseconds
dig from a second client at the same momentNOERROR with the answer
1,500 queries from one device through the routerThe router hit the limit, then REFUSED
A second device asking through the routerstatus: REFUSED, passed on by the router
The same second device asking Pi-hole directlyNOERROR with the answer

The last three rows are the household problem in miniature. One busy device used up the router's quota. A device that had sent one query got refused, only because it asked through the router.

The refused queries were also invisible. After the first run, the query log held exactly the 1,063 queries that got answers. None of the 114 refused ones were there. The code says why: FTL stops before it records anything, because "Pi-hole has never seen it."

How long it lasts#

The windows do not slide. The docs say the interval "is relative to when FTL has finished starting", then "it will advance in steps of the rate-limiting interval". A limited client "will be blocked until the end of the current interval". That is why the log says "at least 13 seconds" one time and "at least 47 seconds" another. The number is just the time left in the window.

In FTL's code, the counter resets to zero when the client is first limited, then counts the refused queries. At the end of the window, if that count is still over the limit, FTL logs "Still rate-limiting" and blocks the client for the whole next window. If not, it logs "Ending rate-limitation" and lets it go.

We watched three patterns:

Load from one clientWhat happened
1,100 queries in one burstRefused for 12 seconds, to the end of the window
A steady 30 queries a second (1,800 a minute)Answered for about 33 seconds, refused for about 27, every minute. No "Still" line
A steady 100 queries a second"Still rate-limiting ... additional 2276 queries", then 6001, then 3761. Refused for 83 seconds after the flood stopped

The middle row is what a busy router looks like. It is never limited for long, but it is refused near the end of every minute. Devices behind it fail in bursts, which is easy to blame on Wi-Fi.

The two real fixes#

Hand out Pi-hole directly. This is the fix the moderator pointed to. Set your router's DHCP server to give out Pi-hole's IPv4 address as the DNS server. Or turn on Pi-hole's own DHCP server and turn off the router's. Then do the same for IPv6: tell the router to stop announcing any IPv6 DNS server, or to announce Pi-hole's IPv6 address. The moderator's advice was to configure the router "to stop advertising any IPv6 as DNS server, or to advertise your Pi-hole host machine's IPv6". Devices only pick this up when their lease renews. FRITZ!Box leases last 10 days by default, per the thread, so reconnect or restart them.

This fix also gives you per-device rows in the query log, instead of one huge row for the router.

Raise the count. If the router cannot be fixed, give it more room. The moderator's rule of thumb: with n clients, "start out with (n ÷ 2 *1000)". For 8 clients that is 4,000, which the thread wrote in v5 form as RATE_LIMIT=4000/60. In v6:

bash
sudo pihole-FTL --config dns.rateLimit.count 4000

In our lab this took effect at once, with no restart. Through the router, 3,500 queries in about seven seconds then all got answers. In Docker, use the environment variable instead:

yaml
environment:
  FTLCONF_dns_rateLimit_count: 4000
  FTLCONF_dns_rateLimit_interval: 60

A value set this way is locked. When we tried to change it from the CLI, FTL said "Config option dns.rateLimit.count is read-only (set via environmental variable)".

The moderator added a warning. A higher limit "may make max concurrent warnings more likely". That is dnsmasq's "Maximum number of concurrent DNS queries reached" message, which the poster later hit too. Pi-hole's docs say it can mean "being spammed with an excessive amount of duplicates".

Turning it off, and the setting that traps you#

The docs say limiting "may be disabled altogether by setting both values to zero". The code needs less. The check runs only while the count is above zero, so count = 0 alone switched limiting off. 3,000 queries in three seconds all got answers.

The interval is the dangerous one. The code that resets each client's counter runs only when the interval is above zero. We set the interval to 0 and left the count at 1,000. The 1,001st query was refused and FTL logged:

text
INFO: Rate-limiting 10.253.53.42 for at least -33 seconds

The negative number is the giveaway. That client was still refused 2.5 minutes later, when we stopped watching. Nothing in the code resets the counter or the block while FTL runs. Setting the count to 0 freed the client at once.

You wantSetResult in our lab
Each device counted on its ownDHCP and IPv6 announcements point at Pi-holeEvery client gets its own 1,000
More room for a router you cannot changecount to n ÷ 2 × 1,000, interval 603,500 through the router at 4,000, no refusals
No limiting at allcount 0 (the docs say both 0)3,000 in three seconds, no refusals
Not thisinterval 0 with count above 0Client blocked for good after 1,000

A worked case: the router at .254#

Take the network from the thread. The router is 192.168.1.254, Pi-hole is 192.168.1.111, and the warning comes a few times a day. Pi-hole's own DHCP hands out 192.168.1.111, so on paper no device should use the router for DNS.

Start with FTL.log. The thread's debug log showed the whole cycle:

text
[2024-12-18 08:54:31.630 4911M] Rate-limiting 192.168.1.254 for at least 8 seconds
[2024-12-18 08:54:39.339 4911/T4947] Still rate-limiting 192.168.1.254 as it made additional 2850 queries
[2024-12-18 08:55:39.401 4911/T4947] Ending rate-limitation of 192.168.1.254

Walk through it. The limit hit with 8 seconds left in the window. In those 8 seconds the router sent 2,850 more queries, so it stayed blocked for the whole next window. Then it calmed down and was released. Add the numbers up: about 3,850 queries in one window. The moderator's 4,000 for eight clients would only just have covered it.

Next, ask what the router sent. The moderator gave this query against Pi-hole's long-term database. Put in the time from the first log line:

bash
pihole-FTL sqlite3 /etc/pihole/pihole-FTL.db "SELECT domain, reply_type, count(*) FROM queries \
WHERE timestamp > strftime('%s','2024-12-18 08:54:31.630', '-1 minute', 'utc') \
AND timestamp <= strftime('%s','2024-12-18 08:54:31.630', 'utc') \
AND client = '192.168.1.254' GROUP BY domain, reply_type ORDER BY 3 DESC LIMIT 10;"

The answer showed app and Microsoft domains, not router domains. The moderator's reading: "It's not your router that issues those queries." Devices were still asking the router. Suppose the IPv4 side is clean, as it was here. Then check IPv6. Look at a phone's DNS servers for a second, IPv6 entry. Look at /etc/resolv.conf on the Pi-hole host for an IPv6 nameserver it never set. Either one means the router is announcing itself. Change that in the router, renew the devices, and watch for the warning to stop.

When this answer stops applying#

Our lab was one Pi-hole v6.9 container in Docker, with a dnsmasq container as the router. We did not test a real consumer router, a real IPv6 network, or how phones and laptops react to REFUSED. Many will try another DNS server if they have one. A limited client that is not your router is a different case. It is a single device sending too much, and the query log will name it. A NAS re-asking for local names can do it. One Pi-hole regular stopped "queries from my NAS flooding Pi-hole" by giving local records a TTL of 2 seconds instead of 0. We did not test FTL restarts, so we cannot say how a restart affects a block in progress.

What to do next#

Find out who is behind the limited address before you change any number. If it is the router, fix the DNS handout on both IPv4 and IPv6, then raise the count only if the router will not cooperate. If you are still choosing a blocker, Pi-hole vs AdGuard Home weighs Pi-hole against its main rival. For the bigger question of how names should flow through a home network, including a second resolver for when this box is down, read DNS for self-hosters.

Questions#

What does a rate-limited client get back from Pi-hole?

An answer with the status REFUSED and nothing in it. It is not a timeout. In our lab, dig came back in a few milliseconds with status: REFUSED and ANSWER: 0. A dnsmasq router in front of Pi-hole passed the same REFUSED on to the device that asked. Other clients that talk to Pi-hole directly kept getting normal answers the whole time, because the limit is per client.

How long does Pi-hole rate-limit a client?

Until the end of the current window, then window by window while the flood goes on. The windows are fixed 60-second steps counted from when FTL started. They do not slide. So the log line says "for at least 13 seconds" or "for at least 47 seconds" depending on when in the window the 1,001st query arrived. If the client sends more than 1,000 more queries while it is blocked, it stays blocked for the whole next window.

Why does the Pi-hole query log not show the rate-limited queries?

FTL drops them before it records anything. The code comment says it plainly: "Pi-hole has never seen it." In our first run the query log held exactly the 1,063 queries that got answers and none of the 114 that were refused. So the dashboard undercounts a limited client. The number in the "Still rate-limiting" log line is the only place the refused count shows up.

How do I change the Pi-hole rate limit in Docker?

Set FTLCONF_dns_rateLimit_count and, if you want, FTLCONF_dns_rateLimit_interval in the container's environment, then recreate it. A value set this way becomes read-only. When we tried to change it with pihole-FTL --config afterwards, FTL answered "Config option dns.rateLimit.count is read-only (set via environmental variable)". Without the variable, pihole-FTL --config dns.rateLimit.count 4000 took effect straight away in our lab.

What is the Pi-hole v6 equivalent of RATE_LIMIT=1000/60?

RATE_LIMIT was the v5 line in /etc/pihole/pihole-FTL.conf. In v6 it became two keys in pihole.toml: dns.rateLimit.count and dns.rateLimit.interval. FTL's legacy reader copies an old RATE_LIMIT value into those keys when it migrates a v5 install. Forum answers that say RATE_LIMIT=4000/60 translate to count = 4000 and interval = 60.

Should I just disable Pi-hole rate limiting?

Only if you know where the load comes from. The limit exists, in the web interface's words, to keep Pi-hole from "getting overwhelmed by rogue clients". Turning it off hides the symptom of a router forwarding for the house, but it also lets one broken device flood your resolver. Fix the DNS handout first. If the router cannot be fixed, raising the count keeps a ceiling in place.

Sources#

Published . Last reviewed . Found something out of date? Tell us and we will fix it and log the change.