Troubleshooting

This section is used for identifying problems when installing and executing the DITA Open Toolkit.

1. Out of Memory Error

In some cases, you might receive a message stating the build has failed due to an "Out of Memory" error. Please follow the steps below to fix this problem:


  1. For Windows, type set ANT_OPTS=%ANT_OPTS% -Xmx256M in the command prompt, you can also choose to add a new opition -Xmx256M to the ANT_OPTS environment variable.

    For Linux, type export ANT_OPTS=${ANT_OPTS} -Xmx256M in the command prompt.

  2. Run the transformation again.

2. java.io.IOException: Can't store Document

In some cases, when you run the JavaHelp transformation, you might receive the exception above. This problem is caused by some HTML files unrelated with the current JavaHelp transformation were found under the output directory. Please follow the steps below to fix this problem:


  1. Change into the output directory.
  2. Clean the output directory.
  3. Run the JavaHelp transformation again.

3. Failed to load message file

In some situations, the toolkit may fails to load the message file due to some exceptions thrown.

To fix this problem, you need to check if there are files 'resource/messages.xml' and 'resource/messages.dtd' in the directory that you run the toolkit. If not, please copy them from the toolkit's root directory.

4. Spaces in file names

Spaces in file names will cause trouble during the processing because Ant use space as the delimiter when processing batch files in a list. Please prevent using spaces in the name of dita files.

5. Stack Overflow

Sometimes, you will receive an error during the transformation which says the stack memory overflows. Please follow the steps below to fix the problem:


  1. For Windows, type set ANT_OPTS=%ANT_OPTS% -Xms512M in the command prompt, you can also choose to add a new opition -Xms512M to the ANT_OPTS environment variable.

    For Linux, type export ANT_OPTS=${ANT_OPTS} -Xms512M in the command prompt.

  2. Run the transformation again.
Related concepts
DITA futures
Building DITA output with Ant
Building DITA output with Java command line
Migrating HTML to DITA
Related reference
DITA release notes
Problem determination and log analysis
Known Limitations
Related information
DITA release history
Tested platforms and tools
Using DITA transforms
Transfomring DITA to Word RTF