Deutsche Version

Back to overview

ALTCHA Spam Protection: Troubleshooting

This documentation always refers to the latest published release.

Live demo: Try this and other plugins live, no installation, no risk: demo.markus-michalski.net

Common problems

Widget is not shown

• Symptom: The "I'm not a robot" checkbox does not appear in the form.
• Check: Are Enable Spam Protection and Enable ALTCHA Widget on? For newsletter and registration also the respective form switch? Does a custom theme override the captcha block without {{ parent() }} (see Storefront Integration)? Does the browser console show JavaScript errors?
• Solution: Correct the settings, run bin/console cache:clear, add parent() to the theme override. After an update also clear HTTP cache, Varnish and CDN, see Installation.

Form is rejected with the general error page

• Symptom: Submitting shows Shopware's general error page instead of a hint at the form.
• Check: This is expected for most rejection reasons. They stay vague on purpose so a bot does not learn which layer stopped it. The reason (reason) is in the Shopware log, see Technical Details.
• Solution: Only a blocked disposable e-mail address shows a concrete message at the e-mail field. For every other reason check the log and adjust the affected layer in the Configuration.

Genuine visitors are blocked

• Symptom: Legitimate visitors cannot submit the form.
• Check: Look up the reason of the rejection in the log.
• Solution: Depending on the reason:
  • gibberish: raise the reject threshold or temporarily set it to 101 (observe only)
  • disposable_email: enter the domain under "Always allowed domains"
  • too_fast: lower the minimum fill time or set it to 0
  • rate_limited: raise Max Requests or widen the time window
  • content_validation_failed: switch off the deprecated content validation or switch on gibberish detection or the disposable e-mail check, which replace it
  • altcha_failed or altcha_missing: see the next sections

All visitors hit the rate limit

• Symptom: The first submissions of different visitors are already rejected with rate_limited, or the challenge endpoint answers 429 early.
• Check: Is the shop behind a reverse proxy or CDN? It may then only see the proxy's address, and all visitors share one limit.
• Solution: Configure the trusted proxies in Symfony so the real visitor IP arrives. As a stopgap you can raise the limit.

The ALTCHA check fails

• Symptom: The submission is rejected with altcha_failed.
• Check: Has the challenge expired (default 5 minutes)? Was the page left open for a long time? Was the same solution sent twice (replay protection)? Did APP_SECRET change while pages were open?
• Solution: Reload the page and submit the form again. If it happens often, raise the challenge expiry.

Widget missing, submission rejected with altcha_missing

• Symptom: The log shows altcha_missing.
• Check: The form was submitted without the widget: theme override without parent(), a cached page from before an update, or JavaScript blocked in the browser.
• Solution: Check the override and caches, see above.

Challenge endpoint answers with HTTP 500 or form pages show an error

• Symptom: /altcha/challenge returns 500, or pages containing a form cannot be rendered.
• Check: Is the environment variable APP_SECRET set and not empty?
• Solution: Set APP_SECRET and clear the cache.

Rate-limit table keeps growing

• Symptom: mmd_altcha_rate_limit_log keeps getting larger.
• Check: Is the message worker running? bin/console messenger:consume scheduled_task
• Solution: Start the worker or clean up manually: bin/console scheduled-task:run mmd_altcha.rate_limit_cleanup

Disposable e-mail list is not refreshed

• Symptom: New disposable domains from the upstream list are missing.
• Check: Is Reject disposable e-mail addresses on for a single sales channel only instead of globally? The weekly task runs only when it is on globally. Can the server reach raw.githubusercontent.com?
• Solution: Run bin/console mmd:altcha:update-disposable-domains, on every node separately when you have several app nodes.

"Blocked domains" view stays empty or does not load

• Symptom: The searchable list under "Disposable E-Mail Addresses" shows nothing or an error.
• Check: Does the logged-in admin user have the permission to read system configuration?
• Solution: Add the permission to the user's role.

Plugin does not load after Composer installation

bin/console plugin:refresh
bin/console plugin:deactivate MmdAltchaIntegration
bin/console cache:clear
bin/console plugin:activate MmdAltchaIntegration
bin/console cache:clear

Known limitations

• The minimum fill time does not work reliably on HTTP-cached CMS pages (contact, newsletter): a bot scraping a cached page can send an old but valid token. Honeypot, ALTCHA and rate limit still apply.
• The trigram table of gibberish detection covers German, English, French, Spanish, Italian and Dutch. Text in other languages, such as Polish or Hungarian, can score high, and so can laughter like "hahahaha". Capitalised names and short words rarely trigger a rejection on their own, but a long lowercase word made of impossible letter sequences can.
• The disposable e-mail list is a snapshot and never catches every disposable domain. Matching walks the domain and its parent domains, it does not use a public-suffix list.
• The rate limit counts only submissions that passed all previous checks. It is a database query followed by an insert, so under many simultaneous requests from one IP the limit can be slightly exceeded.
• If APP_SECRET is empty, the plugin rejects solutions. The challenge endpoint then answers with HTTP 500, and pages carrying the minimum-fill-time token field run into an error.

FAQ

Is data sent to third parties?

Not during form checks. Only the disposable-domain list is fetched by the server through the task or command, without visitor data. See Privacy.

Does the plugin set cookies?

No. The widget is used without its optional cookie feature.

Why does the contact form have no switch of its own?

The contact form is protected as soon as "Enable Spam Protection" is on. There is no additional switch.

Can I configure layers differently per sales channel?

Yes, every setting can be overridden per sales channel. The refresh of the disposable list only checks the switch globally.

Which Shopware versions does the plugin run on?

Shopware ~6.7.0, see the overview.