AEM Guides: Site Generation Fails When xref Uses mailto:# in Link
This article addresses a site generation failure in Adobe Experience Manager Guides when an xref contains a mailto link starting with the # character.
Description description
Environment
Adobe Experience Manager Guides (all versions)
Issue/Symptoms
When generating AEM Sites output using Presets, the process fails if an xref element contains a mailto link that starts with the # character (For example: mailto:#example@example.com).
The following error occurs during site generation:
BUILD FAILED
/mnt/crx/author/crx-quickstart/profiles/ditaot--<profile-id>/DITA-OT/plugins/org.dita.base/build_preprocess.xml:62:
Failed to run pipeline: Expected scheme-specific part at index 7: mailto:#example@example.com
- The issue is reproducible by adding an xref with
mailto:#in any topic and attempting to generate AEM Sites output. - The error occurs during the DITA-OT preprocessing step.
For additional context, see DITA URI-based addressing documentation:
Resolution resolution
-
Update the xref element to use percent-encoding for the # character.
Instead of using<xref>mailto:#example@example.com``</xref>encode the # as%23.For example:
code language-none <xref href="mailto:%23example@example.com" format="html">Contact Support</xref>
2. Ensure the xref uses the href attribute and includes display text.
This helps DITA-OT correctly interpret the link as an external reference.
Save the topic and regenerate the AEM Sites output using Presets.The site generation should now complete successfully without errors.
Cause
The DITA-OT processor interprets the # character as a fragment identifier within URIs. When used directly in a mailto link, it causes URI parsing errors. Percent-encoding the # character as %23 allows DITA-OT to process the link as intended.