This is an automated email from the ASF dual-hosted git repository.
hansva pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/hop.git
The following commit(s) were added to refs/heads/main by this push:
new e105454361 Issue #7250 : Document that UNC paths are not reliably
supported (#7909)
e105454361 is described below
commit e1054543610ef4aa1d4aad7cb0668a2b14d98b74
Author: vbhanuchander-lang <[email protected]>
AuthorDate: Wed Aug 12 02:25:24 2026 -0400
Issue #7250 : Document that UNC paths are not reliably supported (#7909)
vfs.adoc claimed the opposite of the actual behaviour:
UNC names are supported under Windows.
That sentence describes Apache VFS, which the surrounding table is taken
from, not Hop. On #7250 a user lost time to an Excel Input transform that
could not open a UNC path while another transform read the same file, and
hansva confirmed UNC paths are not supported in Hop -- they work in some
cases and mostly do not -- and asked for it to be documented.
Corrects the sentence, and adds a Windows UNC paths section giving the
reason the behaviour looks inconsistent (different transforms reach the
file system by different routes), a warning against relying on it
unattended, and the mounted-drive workaround hansva recommended, with a
variable example so the same pipeline runs on Windows and Linux.
---
docs/hop-user-manual/modules/ROOT/pages/vfs.adoc | 26 +++++++++++++++++++++++-
1 file changed, 25 insertions(+), 1 deletion(-)
diff --git a/docs/hop-user-manual/modules/ROOT/pages/vfs.adoc
b/docs/hop-user-manual/modules/ROOT/pages/vfs.adoc
index 1c8548d171..fc6e15454d 100644
--- a/docs/hop-user-manual/modules/ROOT/pages/vfs.adoc
+++ b/docs/hop-user-manual/modules/ROOT/pages/vfs.adoc
@@ -86,7 +86,7 @@ a|URI Format
`+[file://] absolute-path+`
Where `absolute-path` is a valid absolute file name for the local platform.
-UNC names are supported under Windows.
+UNC paths are accepted by Apache VFS, but are not reliably supported in Hop —
see <<windows-unc-paths, Windows UNC paths>>.
Examples
@@ -271,6 +271,30 @@ Examples
|Zip|see 'jar'|
|===
+[#windows-unc-paths]
+== Windows UNC paths
+
+The table above describes the file system types provided by Apache VFS itself.
+Apache VFS accepts UNC paths such as
`+file://///somehost/someshare/afile.txt+`, but **UNC paths are not reliably
supported in Hop**.
+They work in some cases and fail in others, and which transforms work is not
predictable: the same file may be readable through one transform and not
another, because different transforms reach the file system by different routes.
+
+WARNING: Do not rely on UNC paths in pipelines or workflows you intend to run
unattended.
+
+Use a mounted drive or folder instead, and point Hop at the mount:
+
+* On Windows, map the share to a drive letter and use that letter, for example
`+file:///Z:/somedir/afile.txt+`.
+* On Linux and macOS, mount the share and use the local path, for example
`+file:///mnt/someshare/afile.txt+`.
+
+Referring to the mount through a variable keeps the pipeline portable across
operating systems:
+
+[source]
+----
+# Windows
+NETWORK_PATH=Z:
+# Linux, macOS
+NETWORK_PATH=/mnt/someshare
+----
+
== Supported operations
The matrix below shows which operations each registered provider exposes,
taken from the capability set each provider declares in code.
