Documentation/Troubleshooting

This article contains assistance on troubleshooting build errors with documentation

Out of Memory Error
You might need to allocate more memory to the Java heap space for the Maven plugin to build larger guides. You can use this environment variable:

export MAVEN_OPTS='-Xms256m -XX:MaxPermSize=1024m -Xmx1024m'

If you want to double the allocation, use:

export MAVEN_OPTS='-Xms1024m -XX:MaxPermSize=2048m -Xmx2048m'

Failed to Transform
If you get an error like: "Failed to transform bk_ops_guide.xml", you have forgotten to add xml:id tags to your section. (eg )

2013-09-10 18:15:29.340 | [INFO] 2013-09-10 18:15:29.344 | [INFO] BUILD FAILURE 2013-09-10 18:15:29.346 | [INFO] 2013-09-10 18:15:29.347 | [INFO] Total time: 49.242s 2013-09-10 18:15:29.353 | [INFO] Finished at: Tue Sep 10 18:15:29 UTC 2013 2013-09-10 18:15:29.584 | [INFO] Final Memory: 90M/793M 2013-09-10 18:15:29.590 | [INFO] 2013-09-10 18:15:30.035 | [JENKINS] Archiving /home/jenkins/workspace/gate-openstack-manuals-operations-guide/doc/openstack-ops/pom.xml to /var/lib/jenkins/jobs/gate-openstack-manuals-operations-guide/modules/org.openstack.docs$openstack-ops-manual/builds/2013-09-10_18-14-34/archive/org.openstack.docs/openstack-ops-manual/1.0.0/openstack-ops-manual-1.0.0.pom 2013-09-10 18:15:30.518 | Waiting for Jenkins to finish collecting data 2013-09-10 18:15:30.522 | mavenExecutionResult exceptions not empty 2013-09-10 18:15:30.523 | message : Failed to execute goal com.rackspace.cloud.api:clouddocs-maven-plugin:1.9.2:generate-webhelp (generate-webhelp) on project openstack-ops-manual: Failed to transform bk_ops_guide.xml. 2013-09-10 18:15:30.524 | cause : Failed to transform bk_ops_guide.xml. 2013-09-10 18:15:30.526 | Stack trace : 2013-09-10 18:15:30.528 | org.apache.maven.lifecycle.LifecycleExecutionException: Failed to execute goal com.rackspace.cloud.api:clouddocs-maven-plugin:1.9.2:generate-webhelp (generate-webhelp) on project openstack-ops-manual: Failed to transform bk_ops_guide.xml. 2013-09-10 18:15:30.531 | 	at org.apache.maven.lifecycle.internal.MojoExecutor.execute(MojoExecutor.java:217) 2013-09-10 18:15:30.532 | 	at org.apache.maven.lifecycle.internal.MojoExecutor.execute(MojoExecutor.java:153) 2013-09-10 18:15:30.534 | 	at org.apache.maven.lifecycle.internal.MojoExecutor.execute(MojoExecutor.java:145) 2013-09-10 18:15:30.535 | 	at org.apache.maven.lifecycle.internal.LifecycleModuleBuilder.buildProject(LifecycleModuleBuilder.java:84) 2013-09-10 18:15:30.536 | 	at org.apache.maven.lifecycle.internal.LifecycleModuleBuilder.buildProject(LifecycleModuleBuilder.java:59) 2013-09-10 18:15:30.541 | 	at org.apache.maven.lifecycle.internal.LifecycleStarter.singleThreadedBuild(LifecycleStarter.java:183) 2013-09-10 18:15:30.542 | 	at org.apache.maven.lifecycle.internal.LifecycleStarter.execute(LifecycleStarter.java:161) 2013-09-10 18:15:30.543 | 	at org.apache.maven.DefaultMaven.doExecute(DefaultMaven.java:320) 2013-09-10 18:15:30.544 | 	at org.apache.maven.DefaultMaven.execute(DefaultMaven.java:156) 2013-09-10 18:15:30.548 | 	at org.jvnet.hudson.maven3.launcher.Maven3Launcher.main(Maven3Launcher.java:79) 2013-09-10 18:15:30.550 | 	at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method) 2013-09-10 18:15:30.551 | 	at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:57) 2013-09-10 18:15:30.555 | 	at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43) 2013-09-10 18:15:30.557 | 	at java.lang.reflect.Method.invoke(Method.java:606) 2013-09-10 18:15:30.561 | 	at org.codehaus.plexus.classworlds.launcher.Launcher.launchStandard(Launcher.java:329) 2013-09-10 18:15:30.562 | 	at org.codehaus.plexus.classworlds.launcher.Launcher.launch(Launcher.java:239) 2013-09-10 18:15:30.563 | 	at org.jvnet.hudson.maven3.agent.Maven3Main.launch(Maven3Main.java:174) 2013-09-10 18:15:30.568 | 	at hudson.maven.Maven3Builder.call(Maven3Builder.java:100) 2013-09-10 18:15:30.569 | 	at hudson.maven.Maven3Builder.call(Maven3Builder.java:66) 2013-09-10 18:15:30.573 | 	at hudson.remoting.UserRequest.perform(UserRequest.java:118) 2013-09-10 18:15:30.574 | 	at hudson.remoting.UserRequest.perform(UserRequest.java:48) 2013-09-10 18:15:30.576 | 	at hudson.remoting.Request$2.run(Request.java:326) 2013-09-10 18:15:30.580 | 	at hudson.remoting.InterceptingExecutorService$1.call(InterceptingExecutorService.java:72) 2013-09-10 18:15:30.581 | 	at java.util.concurrent.FutureTask$Sync.innerRun(FutureTask.java:334) 2013-09-10 18:15:30.586 | 	at java.util.concurrent.FutureTask.run(FutureTask.java:166) 2013-09-10 18:15:30.587 | 	at java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1145) 2013-09-10 18:15:30.589 | 	at java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:615) 2013-09-10 18:15:30.592 | 	at java.lang.Thread.run(Thread.java:724) 2013-09-10 18:15:30.594 | Caused by: org.apache.maven.plugin.MojoExecutionException: Failed to transform bk_ops_guide.xml. 2013-09-10 18:15:30.598 | 	at com.agilejava.docbkx.maven.AbstractTransformerMojo.execute(AbstractTransformerMojo.java:179) 2013-09-10 18:15:30.599 | 	at org.apache.maven.plugin.DefaultBuildPluginManager.executeMojo(DefaultBuildPluginManager.java:101) 2013-09-10 18:15:30.601 | 	at org.apache.maven.lifecycle.internal.MojoExecutor.execute(MojoExecutor.java:209) 2013-09-10 18:15:30.605 | 	... 27 more 2013-09-10 18:15:30.607 | Caused by: com.icl.saxon.style.TerminationException: Processing terminated by xsl:message at line 228 2013-09-10 18:15:30.610 | 	at com.icl.saxon.style.XSLMessage.process(XSLMessage.java:90) 2013-09-10 18:15:30.612 | 	at com.icl.saxon.style.StyleElement.processChildren(StyleElement.java:634) 2013-09-10 18:15:30.613 | 	at com.icl.saxon.style.XSLIf.process(XSLIf.java:78) 2013-09-10 18:15:30.617 | 	at com.icl.saxon.style.StyleElement.processChildren(StyleElement.java:634) 2013-09-10 18:15:30.618 | 	at com.icl.saxon.style.XSLTemplate.expand(XSLTemplate.java:225) 2013-09-10 18:15:30.620 | 	at com.icl.saxon.style.XSLCallTemplate.process(XSLCallTemplate.java:187) 2013-09-10 18:15:30.625 | 	at com.icl.saxon.style.StyleElement.processChildren(StyleElement.java:634) 2013-09-10 18:15:30.626 | 	at com.icl.saxon.style.LiteralResultElement.process(LiteralResultElement.java:289) 2013-09-10 18:15:30.630 | 	at com.icl.saxon.style.StyleElement.processChildren(StyleElement.java:634) 2013-09-10 18:15:30.631 | 	at com.icl.saxon.style.LiteralResultElement.process(LiteralResultElement.java:289) 2013-09-10 18:15:30.632 | 	at com.icl.saxon.style.StyleElement.processChildren(StyleElement.java:634) 2013-09-10 18:15:30.633 | 	at com.icl.saxon.style.LiteralResultElement.process(LiteralResultElement.java:289) 2013-09-10 18:15:30.634 | 	at com.icl.saxon.style.StyleElement.processChildren(StyleElement.java:634) 2013-09-10 18:15:30.636 | 	at com.icl.saxon.style.XSLTemplate.expand(XSLTemplate.java:225) 2013-09-10 18:15:30.637 | 	at com.icl.saxon.style.XSLCallTemplate.process(XSLCallTemplate.java:187) 2013-09-10 18:15:30.638 | 	at com.icl.saxon.style.StyleElement.processChildren(StyleElement.java:634) 2013-09-10 18:15:30.640 | 	at com.icl.saxon.style.XSLGeneralVariable.getSelectValue(XSLGeneralVariable.java:238) 2013-09-10 18:15:30.641 | 	at com.icl.saxon.style.XSLWithParam.getParamValue(XSLWithParam.java:48) 2013-09-10 18:15:30.642 | 	at com.icl.saxon.style.XSLCallTemplate.process(XSLCallTemplate.java:164) 2013-09-10 18:15:30.644 | 	at com.icl.saxon.style.StyleElement.processChildren(StyleElement.java:634) 2013-09-10 18:15:30.645 | 	at com.icl.saxon.style.XSLTemplate.expand(XSLTemplate.java:225) 2013-09-10 18:15:30.646 | 	at com.icl.saxon.style.XSLCallTemplate.process(XSLCallTemplate.java:187) 2013-09-10 18:15:30.648 | 	at com.icl.saxon.style.StyleElement.processChildren(StyleElement.java:634) 2013-09-10 18:15:30.649 | 	at com.icl.saxon.style.XSLTemplate.expand(XSLTemplate.java:225) 2013-09-10 18:15:30.650 | 	at com.icl.saxon.style.XSLCallTemplate.process(XSLCallTemplate.java:187) 2013-09-10 18:15:30.652 | 	at com.icl.saxon.style.StyleElement.processChildren(StyleElement.java:634) 2013-09-10 18:15:30.653 | 	at com.icl.saxon.style.XSLOtherwise.process(XSLOtherwise.java:48) 2013-09-10 18:15:30.654 | 	at com.icl.saxon.style.XSLChoose.process(XSLChoose.java:96) 2013-09-10 18:15:30.656 | 	at com.icl.saxon.style.StyleElement.processChildren(StyleElement.java:634) 2013-09-10 18:15:30.657 | 	at com.icl.saxon.style.XSLOtherwise.process(XSLOtherwise.java:48) 2013-09-10 18:15:30.658 | 	at com.icl.saxon.style.XSLChoose.process(XSLChoose.java:96) 2013-09-10 18:15:30.660 | 	at com.icl.saxon.style.StyleElement.processChildren(StyleElement.java:634) 2013-09-10 18:15:30.661 | 	at com.icl.saxon.style.XSLTemplate.expand(XSLTemplate.java:225) 2013-09-10 18:15:30.662 | 	at com.icl.saxon.style.XSLCallTemplate.process(XSLCallTemplate.java:187) 2013-09-10 18:15:30.663 | 	at com.icl.saxon.style.StyleElement.processChildren(StyleElement.java:634) 2013-09-10 18:15:30.664 | 	at com.icl.saxon.style.XSLOtherwise.process(XSLOtherwise.java:48) 2013-09-10 18:15:30.666 | 	at com.icl.saxon.style.XSLChoose.process(XSLChoose.java:96) 2013-09-10 18:15:30.667 | 	at com.icl.saxon.style.StyleElement.processChildren(StyleElement.java:634) 2013-09-10 18:15:30.668 | 	at com.icl.saxon.style.XSLTemplate.expand(XSLTemplate.java:225) 2013-09-10 18:15:30.670 | 	at com.icl.saxon.style.XSLTemplate.start(XSLTemplate.java:198) 2013-09-10 18:15:30.671 | 	at com.icl.saxon.Controller.applyTemplates(Controller.java:255) 2013-09-10 18:15:30.672 | 	at com.icl.saxon.style.XSLApplyTemplates.process(XSLApplyTemplates.java:135) 2013-09-10 18:15:30.674 | 	at com.icl.saxon.style.StyleElement.processChildren(StyleElement.java:634) 2013-09-10 18:15:30.675 | 	at com.icl.saxon.style.LiteralResultElement.process(LiteralResultElement.java:289) 2013-09-10 18:15:30.676 | 	at com.icl.saxon.style.StyleElement.processChildren(StyleElement.java:634) 2013-09-10 18:15:30.678 | 	at com.icl.saxon.style.XSLTemplate.expand(XSLTemplate.java:225) 2013-09-10 18:15:30.679 | 	at com.icl.saxon.style.XSLTemplate.start(XSLTemplate.java:198) 2013-09-10 18:15:30.681 | 	at com.icl.saxon.Controller.applyImports(Controller.java:298) 2013-09-10 18:15:30.682 | 	at com.icl.saxon.style.XSLApplyImports.process(XSLApplyImports.java:71) 2013-09-10 18:15:30.683 | 	at com.icl.saxon.style.StyleElement.processChildren(StyleElement.java:634) 2013-09-10 18:15:30.685 | 	at com.icl.saxon.style.XSLGeneralVariable.getSelectValue(XSLGeneralVariable.java:238) 2013-09-10 18:15:30.686 | 	at com.icl.saxon.style.XSLParam.process(XSLParam.java:76) 2013-09-10 18:15:30.688 | 	at com.icl.saxon.style.StyleElement.processChildren(StyleElement.java:634) 2013-09-10 18:15:30.689 | 	at com.icl.saxon.style.XSLTemplate.expand(XSLTemplate.java:225) 2013-09-10 18:15:30.691 | 	at com.icl.saxon.style.XSLCallTemplate.process(XSLCallTemplate.java:187) 2013-09-10 18:15:30.692 | 	at com.icl.saxon.style.StyleElement.processChildren(StyleElement.java:634) 2013-09-10 18:15:30.693 | 	at com.icl.saxon.style.XSLOtherwise.process(XSLOtherwise.java:48) 2013-09-10 18:15:30.695 | 	at com.icl.saxon.style.XSLChoose.process(XSLChoose.java:96) 2013-09-10 18:15:30.696 | 	at com.icl.saxon.style.StyleElement.processChildren(StyleElement.java:634) 2013-09-10 18:15:30.698 | 	at com.icl.saxon.style.XSLTemplate.expand(XSLTemplate.java:225) 2013-09-10 18:15:30.699 | 	at com.icl.saxon.style.XSLTemplate.start(XSLTemplate.java:198) 2013-09-10 18:15:30.700 | 	at com.icl.saxon.Controller.applyTemplates(Controller.java:255) 2013-09-10 18:15:30.702 | 	at com.icl.saxon.style.XSLApplyTemplates.process(XSLApplyTemplates.java:135) 2013-09-10 18:15:30.703 | 	at com.icl.saxon.style.StyleElement.processChildren(StyleElement.java:634) 2013-09-10 18:15:30.704 | 	at com.icl.saxon.style.XSLTemplate.expand(XSLTemplate.java:225) 2013-09-10 18:15:30.706 | 	at com.icl.saxon.style.XSLTemplate.start(XSLTemplate.java:198) 2013-09-10 18:15:30.707 | 	at com.icl.saxon.Controller.applyTemplates(Controller.java:255) 2013-09-10 18:15:30.708 | 	at com.icl.saxon.Controller.defaultAction(Controller.java:271) 2013-09-10 18:15:30.710 | 	at com.icl.saxon.Controller.applyTemplates(Controller.java:236) 2013-09-10 18:15:30.711 | 	at com.icl.saxon.style.XSLApplyTemplates.process(XSLApplyTemplates.java:135) 2013-09-10 18:15:30.713 | 	at com.icl.saxon.style.StyleElement.processChildren(StyleElement.java:634) 2013-09-10 18:15:30.714 | 	at com.icl.saxon.style.XSLIf.process(XSLIf.java:78) 2013-09-10 18:15:30.715 | 	at com.icl.saxon.style.StyleElement.processChildren(StyleElement.java:634) 2013-09-10 18:15:30.717 | 	at com.icl.saxon.style.XSLOtherwise.process(XSLOtherwise.java:48) 2013-09-10 18:15:30.718 | 	at com.icl.saxon.style.XSLChoose.process(XSLChoose.java:96) 2013-09-10 18:15:30.720 | 	at com.icl.saxon.style.StyleElement.processChildren(StyleElement.java:634) 2013-09-10 18:15:30.721 | 	at com.icl.saxon.style.XSLOtherwise.process(XSLOtherwise.java:48) 2013-09-10 18:15:30.723 | 	at com.icl.saxon.style.XSLChoose.process(XSLChoose.java:96) 2013-09-10 18:15:30.724 | 	at com.icl.saxon.style.StyleElement.processChildren(StyleElement.java:634) 2013-09-10 18:15:30.725 | 	at com.icl.saxon.style.XSLTemplate.expand(XSLTemplate.java:225) 2013-09-10 18:15:30.727 | 	at com.icl.saxon.style.XSLTemplate.start(XSLTemplate.java:198) 2013-09-10 18:15:30.729 | 	at com.icl.saxon.Controller.applyTemplates(Controller.java:246) 2013-09-10 18:15:30.730 | 	at com.icl.saxon.Controller.run(Controller.java:178) 2013-09-10 18:15:30.732 | 	at com.icl.saxon.Controller.transformDocument(Controller.java:1086) 2013-09-10 18:15:30.734 | 	at com.icl.saxon.Controller.transform(Controller.java:953) 2013-09-10 18:15:30.735 | 	at com.agilejava.docbkx.maven.AbstractTransformerMojo.execute(AbstractTransformerMojo.java:163) 2013-09-10 18:15:30.737 | 	... 29 more 2013-09-10 18:15:30.747 | channel stopped

ClassNotFoundException
You may need a modified settings.xml and if you already have M2_HOME set, you might see an error about "java.lang.ClassNotFoundException: org.codehaus.plexus.classworlds.launcher.Launcher" - just run unset M2_HOME. Here is a copy of a working settings.xml file:

 Rackspace Cloud Research  Rackspace Cloud Research repos.rackspace.cloud.snapshots http://maven.research.rackspacecloud.com/content/groups/public/ true true   repos.rackspace.cloud.snapshots http://maven.research.rackspacecloud.com/content/groups/public/ true true  