AEM Troubleshooting Guide

Modified on Fri, 28 Jul, 2023 at 11:41 AM


The first version of Schema App AEM Connector has been tested in the following environment:

  • AEM 6.4 and 6.5

  • 1 dispatcher and 1 publisher instance. (Support for multiple dispatchers and publisher instances will be available in v1.2)

  • Architectures without a CDN.

Troubleshooting Guide

Is the dispatcher configured for Schema App requests?
To configure dispatcher for Schema App requests, please see instruction below

In your AEM instance's source project:

  • Navigate to and edit “[base project]/dispatcher/src/conf.dispatcher.d/filters/filters.any”. 

  • Add an entry similar to this:

/005 { /type "allow" /method "POST" /url "/bin/schemaApp/*" } # allow schemaApp bin path access

  • After adding the line, save the file, commit the change to git, and rebuild the instance.

Are POST calls allowed from Schema App Client?
POST calls are necessary to update the schema markup cache on each page. To allow POST calls from Schema App Client to AEM, please see instruction below

  • Go to system/console/configMgr

  • Search ‘Apache Sling Referrer Filter’

  • Check  ‘Allow Empty’ Checkbox.

Referrer Filter settings

Have you checked your Account ID, website domain and API keys against your account in 

For instructions on how to get these details please check the Installation Guide AEM Installation Guide

Have you included the deployment javascript in relevant page headers?

Ensure the right URLs are selected for Schema App configuration in AEM. See AEM Installation Guide

Do you have a CDN? 
And, if so, is it configured to allow POST requests through and obey caching rules from origin so that it updates when new JSON-LD is loaded? 

Have you added Schema App connector configuration to the page (via page properties in Author)?
For instructions on how to add the configuration please check the Installation Guide AEM Installation Guide


What are we changing on the website?
Schema App does not change your website content, but rather optimizes content on the website with metadata. We add a Javascript which generates schema markup in JSON-LD format. See more information on how it works AEM Solution Description 

What is Schema Markup? What is JSON-LD?  

Total performance impact of highlight.js: <59ms

However, If Highlight.js fails to match when evaluating a Highlighter template, it continues to monitor the page with the wait time and retries decaying over time. This may cause an impact on page performance if it needs to retry a lot.  Each retry duration would be a fraction of the initial attempt.

What is the impact of the script on page speed?  
Schema Markup is a structured Data Vocabulary ( that helps search engines better understand the information on your website in order to deliver rich results. Markups allow search engines to see the meaning and relationships behind entities on your website.

JSON-LD (JavaScript Object Notation for Linked Data) is a method of encoding linked data using JSON and is most commonly used encoding of schema markup.

What way does the publishers and dispatchers are set up, also sending out to a CDN?
The Author instance will accept webhooks and we need you to ensure your author instance can accept POST requests.  The Author will refresh each Publisher, which in turn updates their associated dispatcher using standard AEM mechanism.

With regards to CDNs (Akamai, Cloudfront, etc.) a change to the JSON-LD (JavaScript Object Notation for Linked Data is a method of encoding linked data using JSON) will be like any content change to a webpage and generate a new version of the webpage.  You simply need to make sure that your CDN is configured correctly to recognize when your pages have changed.

Failover - how many times will it retry? Where can we find the webhook results?
Webhooks will automatically retry 5 times. Webhook results are available at  

International setup is configured in Europe, US, and Australia. Need to make sure it won't have a bigger impact. This will go into the overall install base. How will AEM work in this scenario?
AEM plugin only runs for each domain that you configure.  Each domain is a separate configuration so you can run this on as few or as many of your different regional websites as you like.  If the regions are all part of one massive website, you can also manage configuration on a folder by folder / page by page basis as needed. These are configured as accounts or sub accounts in Schema App Highlighter during the account setup.

Expand the CMS architecture and integration in the environment and the webpages. What lives in CMS and also in pages. Where is the integration  - when it talks to the CMS itself, or pages involved in the CMS. Pages, library, etc.
JSON-LD is stored under the page, content is injected at runtime in the page header. 

Within AEM, you can select the sites that it can be deployed on and add some additional granularity.  More at an environmental level but for a project within AEM.
the See above note about regional / different websites.  A single AEM deployment can support multiple different websites.  The Schema App Connector needs to be installed just once per AEM deployment but configured individually for each website there-in.

I need to remove the schema app script for any pages on the site? How can I do this?
Go to the author and remove the schema app configuration from that page’s page properties and publish it.

We have websites on both AEM On-Prem and AEMaaCS. Can Schema App integrate with both? 
Yes, it is possible to integrate with both On-Prem and AEMaaCS for different pages of a website. 

Was this article helpful?

That’s Great!

Thank you for your feedback

Sorry! We couldn't be helpful

Thank you for your feedback

Let us know how can we improve this article!

Select at least one of the reasons
CAPTCHA verification is required.

Feedback sent

We appreciate your effort and will try to fix the article