I'm running DITA-OT 3.6 in Windows. Running build jobs at the command prompt.
I have a short document made up of 18 .dita topics. It builds fine as a PDF.
When I run the build with transform type 'html5', it should create 1 .html file per input topic.
But the output is missing 1 or more of the expected .html files.
The number of missing .html files varies from run to run.
The missing .html files themselves are different each time.
I run the build with the exact same command, .dita files and environment. I literally run the job one after another without touching anything, and different topics go missing each time.
Dita build command below. Yes, it is very long.
dita -f html5 -i C:\perforce\workspaces\helena.nash_ws\cust_eng\techpubs\Source\DEV\DEV_HTML\DITA\PowerVR\bm_gfx_relnotes_XT.ditamap -o C:\perforce\workspaces\helena.nash_ws\cust_eng\techpubs\Source\DEV\DEV_HTML\DITA\PowerVR\buildscripts\2025-04-04_153300\SeriesDXS\IMG_D-Series_DXS-8-256_72.3.408.1039_ReleaseNote_1_13_html --outputFile.base=IMG_D-Series_DXS-8-256_72.3.408.1039_ReleaseNote_1_13 -t C:\perforce\workspaces\helena.nash_ws\cust_eng\techpubs\Source\DEV\DEV_HTML\DITA\PowerVR\buildscripts\2025-04-04_153300\temp --document.status=Complete --propertyfile=C:/perforce/workspaces/helena.nash_ws\cust_eng\techpubs\Source\DEV\DEV_HTML\DITA\PowerVR\build.properties "--confidential.level=Strictly Confidential" --verbose -filter "C:\perforce\workspaces\helena.nash_ws\cust_eng\techpubs\Source\DEV\DEV_HTML\DITA\PowerVR\ditavals\common\filter_no_internal.ditaval;C:\perforce\workspaces\helena.nash_ws\cust_eng\techpubs\Source\DEV\DEV_HTML\DITA\PowerVR\ditavals\common\filter_audience_techspec.ditaval;C:\perforce\workspaces\helena.nash_ws\cust_eng\techpubs\Source\DEV\DEV_HTML\DITA\PowerVR\ditavals\common\filter_include_SIMULATOR_XCELIUM.ditaval;C:\perforce\workspaces\helena.nash_ws\cust_eng\techpubs\Source\DEV\DEV_HTML\DITA\PowerVR\ditavals\gfx_configs\MODERN_72.V.408.1039.ditaval;C:\perforce\workspaces\helena.nash_ws\cust_eng\techpubs\Source\DEV\DEV_HTML\DITA\PowerVR\ditavals\gfx_relnotes\Modern_72.3.408.1039_relnote.ditaval;C:\perforce\workspaces\helena.nash_ws\cust_eng\techpubs\Source\DEV\DEV_HTML\DITA\PowerVR\ditavals\common\filter_delivery_target_pdf.ditaval;C:\perforce\workspaces\helena.nash_ws\cust_eng\techpubs\Source\DEV\DEV_HTML\DITA\PowerVR\ditavals\common\filter_delivery_target_html.ditaval;C:\perforce\workspaces\helena.nash_ws\cust_eng\techpubs\Source\DEV\DEV_HTML\DITA\PowerVR\ditavals\common\filter_platform_exclude_all.ditaval;C:\perforce\workspaces\helena.nash_ws\cust_eng\techpubs\Source\DEV\DEV_HTML\DITA\PowerVR\ditavals\common\filter_audience_exclude_all.ditaval" --args.css=css_tech_comms_dita_to_html.css --args.cssroot=C:\perforce\workspaces\helena.nash_ws\cust_eng\techpubs\Source\DEV\DEV_HTML\DITA\PowerVR\CSS --args.copycss=yes --args.csspath=css --nav-toc=full --args.hdr=C:\perforce\workspaces\helena.nash_ws\cust_eng\techpubs\Source\DEV\DEV_HTML\DITA\PowerVR\buildscripts\2025-04-04_153300\SeriesDXS\IMG_D-Series_DXS-8-256_72.3.408.1039_ReleaseNote_1_13_html\hdr_tech_comms_dita_to_html.xml --args.figurelink.style=TITLE --args.tablelink.style=TITLE
The temp directory contains all the source .dita files, even the ones for the missing topics. So there might be 18 input .dita files in temp, but only 17 .html files in the output directory.
The only clues I have are some error messages in the log. They are all in this format:
[xslt] Failed to transform document: Failed to transform document: Failed to create directory <filepath of output html directory>.
There is 1 error message per missing .html file.
The named directory corresponds to the target directory of a missing .html file.
Other .html files are successfully written to that directory.
The error messages all appear toward the end of the build log, in the html5.topics.common section.
Example of full error message:
[xslt] Failed to transform document: Failed to transform document: Failed to create directory C:\perforce\workspaces\helena.nash_ws\cust_eng\techpubs\Source\DEV\DEV_HTML\DITA\PowerVR\buildscripts\2025-04-04_152347\SeriesDXS\internal\IMG_D-Series_DXS-8-256_72.3.408.1039_ReleaseNote_1_13_internal_html\topics-relnotes\common
In the same block of html5.topics.common log messages, there is a full set of 'processing file messages', one for each topic, including the ones that go missing.
[xslt] Processing file: <temp filepath of dita input topic>
If I run the same build enough times, eventually I can assemble a full set of .html files to create a full set. But that's not ideal.
So all I really know is that: in the html5.topics.common stage, 1, 2 or 3 .dita topics fail to materialise as .html output files, and it has something to do with a 'failed to create directory' message, and the directory in question actually exists.
I'm not sure what else to try.
The topics all check out fine in OxygenXMl. There are no funny characters or attributes.
Has anyone else experienced this? Maybe I need to download a newer version of DITA-OT. I've been looking through release notes for newer versions of DITA-OT but I'm not sure what I'm looking for.
Update - I spent a day playing with output and temp folders. Although initial tests looked promising, I did still get the occasional error, again, seemingly at random. More errors with longer documents, less with shorter documents.
Then I started to remove dita arguments, one by one, and running test builds to see if I got the error.
When I got down to removing the --propertyfile argument, the error disappeared.
The property file contains this line:
parallel = true
Disclaimer: I have inherited our code from a departed colleague, so I had not seen that line before.
From https://www.dita-ot.org/dev/parameters/parameters-base: "Run processes in parallel when possible. The allowed values are true and false; the default value is false."
My seemingly random 'Failed to create folder' error felt a lot like the result of parallel processing occasionally clashing when creating output topic folders.
So I removed parallel = true from the propertyfile.
Everything works fine now.
It was at that point that I discovered this thread from May 2022: https://github.com/dita-ot/dita-ot/issues/3917
Sadly I had not found that thread earlier - it described the error as "folder could not be created", while I was seeing the error "Failed to create directory". Which is close, but would never have come up on my searches :)
I see that a fix was put in for DITA OT 3.7.1, so I might upgrade to that anyway, so I don't have to remember to avoid parallel = true in the future.
:)