Troubleshooting 

A scan finds nothing 

  • Open Settings and check which fields are enabled on the Scan fields tab. AQG discovers the fields automatically the first time the module opens or a scan runs; if the tab is still empty, press Refresh fields. After changing the selection press Save changes.
  • Check the Rules tab for rules that were disabled earlier.
  • Verify that the scanned page really is inside the site you selected in the module filter.

A field is not offered for scanning 

Press Refresh fields on the Scan fields tab. AQG discovers RTE and file fields from TCA, so a field that was added by an extension or by a TCA override appears only after a new discovery run. Fields whose TCA type AQG does not support are not listed.

CKEditor does not highlight anything 

  • Highlighting is registered for tt_content RTE fields of saved records. It is not active for a record that has never been saved.
  • Clear the TYPO3 caches and reload the backend after an update, so that the JavaScript modules are re-read.
  • Check the browser console for module loading errors.

The rendered page check fails 

  • The check requests the page from your own frontend. Make sure the TYPO3 frontend is reachable from the web server itself, including any HTTP basic authentication or IP restriction in front of it.
  • Pages that return an error page instead of the expected content are detected and reported as failed instead of being analysed.
  • Hidden pages are only rendered when a scanner token is configured, see Scanner token.
  • Page types that do not deliver HTML, for example feeds or downloads, are skipped.

The licence is not accepted 

The Licence tab explains the problem, offers the matching next step (for example renew, manage domains or validate again) and shows the machine-readable reason code. Administrators also see the notice in the overview.

invalid_key
The key does not exist. Check for copy and paste errors, or copy the key again from the customer portal.
expired
The licence has ended. Renew it in the customer portal.
trial_expired
The trial has ended. Choose a plan on the pricing page to keep the licensed features.
inactive
The licence is not active. Open the customer portal to reactivate it.
trial_revoked
The trial was revoked. Contact support.
trial_not_verified
The trial could not be verified yet. Validate again from the production domain.
domain_mismatch / trial_domain_mismatch
The key is bound to a different domain. Activate the current domain under Licence domains or in the customer portal; for a trial key, choose a plan for this domain or contact support.
domain_not_activated
A site of this installation uses the domain, but it is not activated for the licence. Activate it under Licence domains or in the customer portal.
domain_not_detected
No site of this installation uses the domain, so the licence cannot cover it. Check the base URL in the Site Configuration, then validate again.
domain_limit_reached
All domain slots of the plan are used. Deactivate a domain under Licence domains or in the customer portal (on PRO, 90 days after it was activated), or switch to Agency for unlimited domains.
licence_project_mismatch / trial_project_mismatch
The key is registered to a different TYPO3 project. Use the key of this project; if the installation was moved or rebuilt, contact support.
api_unreachable / rate_limited
The licence service could not be reached, or asked AQG to slow down. Validate again later, and check outbound HTTPS access to https://api.priebera.sk and whether an endpoint override is set by mistake. AQG keeps the last validation result for up to 48 hours; without one it falls back to the Free feature set until the next successful validation.

Validation results are cached: valid results for one hour, invalid results for five minutes, trial results for fifteen minutes. After fixing a problem it can take a moment until the new state is visible; pressing Validate re-checks immediately.

The backend still behaves like the previous version 

TYPO3 changes the address of extension scripts only when an extension's installed version changes. If AQG's files are updated without a new installed version, for example as a path or VCS package (dev-main) or by copying files without composer update, browsers may keep running the previous scripts for as long as the web server allows them to be cached.

  • The Page module indicator, the settings and the page detail load their scripts with a version of the file content and always get the current script.
  • For the AQG backend module, run composer update priebera/typo3-a11y-quality-gate after updating the files, so the installed version changes, or reload the backend with the browser cache disabled.

Remote scans do not start or find nothing 

  • Only one remote scan per site can run at a time. A parallel submit is rejected with a conflict; wait for the running scan.
  • Hidden pages need a scanner token, see Scanner token.
  • A protected environment needs the basic authentication credentials, see HTTP basic authentication.
  • Check the excluded URL patterns. Too broad a pattern removes most of the site from the scan.
  • Verify that the site is reachable from the internet. The crawler is a hosted service and cannot reach installations that are only available internally.
  • Site not reachable from the internet means the base URL of the site's Site Configuration resolves to a local or private network address — typically a development host such as *.ddev.site or localhost on a server that is otherwise public. AQG derives every scan URL from the Site Configuration and the scanner refuses such addresses, so give the site a public base URL, or a base variant for the application context of this installation, or scan the site where it is publicly deployed. This is not a licence problem.
  • Site address not found means the scanner could not resolve the host name of the site's base URL on the internet, for example because it only resolves inside a VPN or an internal DNS. Check the base URL in the Site Configuration.
  • The Free Remote Preview shows Free Remote Preview needs a public site address instead of a scan button when the Site's base URL is a local, development or internal address such as *.ddev.site or localhost. Content scans work there; run the preview in a publicly reachable installation.
  • Findings that are not mapped to TYPO3 records usually mean the AQG frontend markers are missing, see Site settings (site sets).

AI suggestions are not offered 

  • AI requires an active licence and a configured provider key.
  • Link text and iframe title suggestions have their own toggle, which is off by default.
  • The connection must be verified with Test connection for the current key, model and prompt version.
  • Suggestions are only offered for the supported rules listed in Which findings get suggestions.
  • unsupported_context means AQG could not identify exactly one supported element from the stored finding, so it refuses instead of guessing.

The quality gate does not react 

  • Check publish_mode. 0 disables the gate.
  • Blocking mode requires an active licence; without one the gate can only warn.
  • The gate uses stored findings. Scan the page before testing.
  • Ignored findings do not count towards the thresholds.
  • With threshold_warning = -1 warnings never trigger the gate.

PDF export is unavailable 

PDF export requires an active licence and the mpdf/mpdf library. In Classic installations the library must be provided by the installation.

Encrypted values cannot be saved 

The remote basic authentication password and the AI provider key are encrypted with the PHP sodium extension. Install and enable ext-sodium on the web server and on the CLI.