Skip to the content
Documentation
Help Start
Reading in:
  • German: 9,110 of 9,110 pages
About the help in other languages
All help pages

Request shield: troubleshooting

Symptoms of the request shield with their cause and fix - did not run for this page, rules cannot be read, everything passes, root-owned files, editors sent to the browser check, 429 for real visitors, 405 for forms and…

Download as PDF

Address: https://doc.exponential.earth/learninminutes/exphelp/viewer/help/request-shield/troubleshooting.md

On this page

Request shield: troubleshooting

Contents

  1. First aid
  2. Symptoms, causes and fixes
  3. Real visitors get 429
  4. Forms, the API or the layout editor get 405
  5. Preloaders, warmers and your own scripts
  6. A proxy, CDN or second web server in front
  7. Shared hosting
  8. Finding out why a request was decided

First aid

When you suspect the shield of refusing real visitors and need the site to work now: press Pause on the dashboard, or create the file var/request-shield/PAUSED on the server. The shield then decides nothing, on every server, from the next request. Find the cause in the log, fix it, then Switch on.

Symptoms, causes and fixes

SymptomCauseFix
Dashboard: "The shield did not run for this page"the hook is not in config.php, or Velocity was not restarted after adding it, or Velocity runs an index.php older than 6.0.15add the hook (the guide); ./console exp:velocity restart
"The rules cannot be read"a mistake in a rule filebin/request-shield check <main rule file> names the file and line
Everything passes in enforce mode; PHP's error log says the shield failed and let the request throughthe shield fails open: a store or cache directory it cannot writemake var/request-shield/ writable by the site's PHP user
Files in var/request-shield/ owned by root, the site cannot read themthe command line was run as rootrun bin/request-shield as the web user; fix the owner
An editor gets the browser check page in the administrationthe administration asks for the browser check once per passallow JavaScript and cookies; for a fixed office address, exempt <address> in the rule file
Background requests in the administration fail with 429a background request without a pass gets the check as JSONthe page reloads itself; name other background paths with api-path
The layout editor says "Something went wrong" when you discard a draft or save (405 by rule methods in the log)the site's copy of the admin rules predates exp_request_shield 0.0.1.4 and allows only GET, HEAD, POST and OPTIONStake EXP-ADMIN-SPA (or EXP-AH-SPA on an admin host) and its method line from the extension's rules/exponential-admin-uri.rules (or -host.rules) into the site's copy
Setup > Preload sites stops after about 120 pages with 429, or the check after exp:upgrade fails on /user/login with 429the pace limit or the login's browser check answered the server's own requestsupdate exp_request_shield to 0.0.1.5 or later: the kernel signs its own requests (X-Exp-Self) and the shield lets them pass
Real visitors get 429the browser check page (status 429, normal: the browser solves it), or a budget shared by many visitorsReal visitors get 429
A form, the REST API or the layout editor answers 405the method is not allowed there (EXP-POST, method)Forms, the API or the layout editor get 405
Nearly every log line shows the same network; or nothing is ever counteda proxy or CDN in front that the rules do not trustA proxy, CDN or second web server in front
Crawlers get the browser check on PDFs or the searcha crawler that only sends a search engine's name is treated like any visitor; verified crawlers never get the checknothing to fix; to welcome a crawler of your own, crawler <kind> ua /<pattern>/ dns <suffixes>
After replace [EXP-SEARCHES] ... every page counts against the search budgetthe shipped rule stands inside a match block; the replacement was written without atadd at regex (?i)/content/(advanced)?search(/|$) (cookbook)
test fails shipped examples after a replace (expected uncached, got check by EXP-SEARCHES)the shipped examples were written for the old numbersexpected; your examples next to the replace count
A rule from a new extension release is missing on the site (for example EXP-ADMIN-SPA, EXP-IMAGES)the copies in settings/request-shield/ are written once and never updated by an updatecompare them with extension/exp_request_shield/rules/ (cookbook)
A page alias is refused (404 by EXP-MODULES or EXP-SYSVIEW)the alias starts with a module nameadd the alias as an exception with an expect example (Monitor and enforce)
bin/request-shield test fails five examples with Origin: https://www.example.org (403 by EXP-ORIGIN) after you named your hoststhe shipped examples use the documentation domain www.example.orgadd host www.example.org: a reserved domain, never a real visitor's
The dashboard chart is emptythe rules name no log file, or log-level offset log ...; set log-level flag
/rs/... answers 403the default rule SITE-DASH closes the library's own pages to all but the serveropen them for your addresses or with a token (the extension's dashboard.md)
A mode button is disabledthe web server cannot write the rule file or its directorymake it writable, or change set mode on the server
Under Velocity, X-RS: allow-uncached shield error on refusalsa library whose inner steps changed: the extension fell backupdate the extension

Real visitors get 429

First look at the log line (Setup > Request shield > Log, or grep the address' network in var/request-shield/log/shield.log):

Log lineWhat happenedWhat to do
challenge 429 "always" rule=EXP-LOGIN (or EXP-FORMS, EXP-ADMIN-CHECK)the browser check page was sent; its status is 429. A browser with JavaScript and cookies solves it in a second and goes onnothing. If the visitor stays on the page: JavaScript or cookies are blocked (a privacy add-on), which the page says
challenge 429 "pages" rule=EXP-PACEmore than 120 pages a minute from one address: often an office, a school or a mobile network behind one IPv4 addressexempt the office's address, or a faster pace (cookbook)
challenge 429 "images" rule=EXP-IMAGESa page with thousands of new images (aliases made on demand)a bigger image budget (cookbook)
challenge 429 "searches" rule=EXP-SEARCHESmore than ten searches a minutenormal for a person only when paging fast; raise the budget if the search is cheap
throttle 429 "banned"a ban (ban after ...)the visitor caused many refusals first; find those lines. A ban ends by itself (at most after ban-max); the library's lists page (/rs/waf/lists) can lift it earlier
the same visitor checked again and againthe pass is bound to the browser (bind-user-agent on), or the secret differs between serversone secret on every server (several web servers)
everyone gets 429 at the same timeall visitors share one address: a proxy in front is not trusteda proxy in front

While you look, Monitor on the dashboard lets everyone in and still logs what would have been decided.

Forms, the API or the layout editor get 405

The log says reject 405 "method". The shield allows POST only where Exponential takes forms (EXP-POST), and PUT, PATCH and DELETE only for the layout editor's API (EXP-ADMIN-SPA).

  • A form of your own extension: allow POST **/<module>/** (cookbook).
  • The REST API: method ... PUT PATCH DELETE and allow PUT PATCH DELETE /api/** (cookbook).
  • The layout editor's "discard draft" or "save" says "Something went wrong": the site's copy of the admin rules predates exp_request_shield 0.0.1.4; take EXP-ADMIN-SPA and its method line from the extension's rules/exponential-admin-uri.rules (or EXP-AH-SPA from -host.rules).

Preloaders, warmers and your own scripts

The pace allows 120 pages a minute per address, and the login always asks for the browser check, which no script can solve. So a crawler of your own is checked after 120 pages:

  • Setup > Preload sites, the upgrade's address check, static publishing: they sign their requests (X-Exp-Self) since exp_request_shield 0.0.1.5 with the kernel from 2026-11-14 on. Update both.
  • A script of your own on the same installation: sign it with expRequestShield::selfHeader() (cookbook).
  • A tool on another machine (a CDN's warm-up, an SEO crawler): exempt <its address> until <day>.
  • A signed request still gets 429: the signature is older than two minutes (make one per request), was made for another address or method, or the script cannot read var/request-shield/cache/self.key (run it as the site's user).

A proxy, CDN or second web server in front

SetupSymptom without the fixFix
Cloudflare or another CDNevery visitor seems to come from the CDN: they share one budget and get 429 togethertrust the CDN's ranges, or let the web server set REMOTE_ADDR (mod_remoteip, nginx real_ip) (cookbook)
nginx in front of Apache on the same machineevery request comes from 127.0.0.1, which is exempt: nothing is ever counted or checkedtrust 127.0.0.1 ::1 and X-Forwarded-For from nginx (cookbook)
a load balancer and two web serversvisitors are checked again on the other server; budgets count twice as highone secret for all, store file on a shared folder (cookbook)
LiteSpeed with Cloudflareas for Cloudflare"Use Client IP in Header" for trusted addresses, or trust

The shield believes X-Forwarded-For only from a trusted address, so a visitor cannot pretend to be someone else by sending the header.

Shared hosting

SymptomCauseFix
check says tier S0: budgets, bans and the pass cookie are offno writable directory for the storemake var/request-shield/ writable for the site's PHP user
check says tier S1no APCu: counters in filesnothing to fix; about 25 microseconds a request
PHP's error log: open_basedir restriction from the shieldstore-dir or log outside the allowed folderskeep both inside the installation (var/request-shield/...)
The deploy user and the web server's user cannot read each other's filesthe shield writes 0600set file-mode 0640, set dir-mode 02750, a shared group

Finding out why a request was decided

The log names the rule. To see the decision step by step, on the server, as the web user:

php extension/exp_request_shield/bin/request-shield trace settings/request-shield/request-shield.rules "GET https://www.example.org/the/path"

With set debug-header on in the rule file, every answer carries an X-RS header with the decision; switch it off again afterwards.

Something wrong on this page? Report an error

Documentation license

This documentation is free documentation, licensed under the GNU Free Documentation License 1.3 or later.

Exponential Copyright © 1998-2026 Exponential Foundation and 7x