Add some additional information to the explanation of the DOTX010E error

[stefan-jung]

Expected Behavior

The DOTX010E error might be triggered as a side effect of too long paths. Therefore, the conkeyrefs are not resolved. I have lost a significant amount of my lifetime to figure this out. In our case the error was thrown on a CI runner but not on the local computers. We have intentionally a deeply nested directory tree and quite long filenames, because we have a complex monolithic repository.

Actual Behavior

It is not mentioned, that this could be related to too long filepaths.

Possible Solution

Add a sentence to the explanation of the error message like: "This error is sometimes thrown as a side-effect of too long paths to either the source or the target topic of the content reference."

[infotexture]

@stefan-jung Are you sure those paths are valid URIs?

The appearance of this message suggests they might not be.

• Can you provide examples of the paths that trigger this error in your environment?
• If the same paths work locally but break in CI, how likely is the path length the problem?

At first glance, it seems odd that the toolkit would stop parsing paths at a certain length, so I'm not sure adding that caveat to the docs is the right approach.

If it does, it may be a bug that could be fixed.

@jelovirt @robander Does this sound at all familiar?

[lief-erickson]

Path length can sometimes be an issue on certain versions of Windows.

https://learn.microsoft.com/en-us/windows/win32/fileio/maximum-file-path-limitation

[stefan-jung]

@infotexture Yes, I'm sure. We can build the deliverables without any errors on various Windows machines. The error is only thrown on GitHub Actions (Ubuntu). We have had issues with path lengths every now end then, especially when some writers mount SharePoint libraries or Git repositories via VM to a drive letter Z:\ or similar. A path which works for them can break on a different machine, when the library is mounted to, for example, C:\Users\MyUserName\MyCompany - SharePoint\Library ABC. The error went away, when I renamed a few directories to shorten the paths.

[stefan-jung]

@lief-erickson in this case it works fine on Windows, but not on GitHub Actions (Ubuntu).

[stefan-jung]

The important aspect is the length in Bytes, not in characters. The Byte length can also be calculated with Schematron, based on Michael K.s answer:

<?xml version="1.0" encoding="UTF-8"?>
<sch:schema xmlns:sch="http://purl.oclc.org/dsdl/schematron" queryBinding="xslt3"
    xmlns:sqf="http://www.schematron-quickfix.com/validator/process">
    <sch:pattern>
        <sch:rule context="*[contains(@class, ' topic/topic ')]">
            <sch:let name="doc" value="base-uri(.)"/>
            <sch:let name="doc-bytes" value="
                sum(for $c in string-to-codepoints($doc) 
                return (1 + number($c > 127) + number($c > 2047) + number($c > 65535)))
                "/>
            <sch:report test="'a' = 'a'">
                The filepath "<sch:value-of select="$doc"/>" has a length of <sch:value-of select="$doc-bytes"/> Bytes.
            </sch:report>
        </sch:rule>
    </sch:pattern>
</sch:schema>

Sample project: bytes.zip

[infotexture]

@stefan-jung @lief-erickson Thanks for the additional context.

Resolved for 4.2.2 in 0f9db57. See deploy preview:

This message may also appear if the path to either the source file or the content reference target exceeds the platform’s maximum path length in bytes.