Troubleshooting DITA Transformation Errors

If a DITA transformation results in errors or warnings, the information is displayed in the message panel at the bottom of the editor. The information includes the severity, description of the problem, the name of the resource, and the path of the resource.

To help prevent and solve DITA transformation problems, follow these steps:

1. Validate your DITA documents by using the Validate action from the Validation toolbar drop-down menu, the Document ⇒ Validate menu, or from the Validate menu when invoking the contextual menu in the Project view.
2. If this action results in validation errors, solve them prior to executing the transformation. Also, you should pay attention to the warning messages because they may identify problems in the transformation.
3. Run the DITA transformation scenario.
4. If the transformation results in errors or warnings, they are displayed in the Transformation problems message panel at the bottom of the editor. The following information is presented to help you troubleshoot the problems:
   • Severity - The first column displays the following icons that indicate the severity of the problem:
     • Informational - The transformation encountered a condition of which you should be aware.
     • Warning - The transformation encountered a problem that should be corrected.
     • Error - The transformation encountered a more severe problem, and the output is affected or cannot be generated.
   • Info - You can click the See More icon to open a web page that contains details about DITA-OT error messages.
   • Description - A description of the problem.
   • Resource - The name of the transformation resource.
   • System ID - The path of the transformation resource.
5. Use this information or other resources from the online DITA-OT community to solve the transformation problems before re-executing the transformation scenario.
6. If you need to contact the oXygen technical support team, they will need you to send the entire transformation scenario execution log. To obtain it:
   1. Go to Options ⇒ Preferences ⇒ DITA preferences page and set the Show console output option to Always.
   2. Execute the transformation scenario again. The console output messages are displayed in the DITA OT view.
   3. Copy the entire log, save it in a text file, then send it to the oXygen technical support team.
   4. After your issue has been solved, go back to the Options ⇒ Preferences ⇒ DITA preferences page and set the Show console output option to When build fails.