[Feature Request]: Improve exception visibility in FileSystems.matchSingleFileSpec to prevent masking of root-cause Exceptions #40076

What would you like to happen?

Internal - b/542081962

Currently, when a pipeline uses FileSystems.matchSingleFileSpec(String spec) to resolve a file, it can suffer from a critical observability gap. If the underlying file system (such as Google Cloud Storage) rejects the read due to any error, the actual root-cause exception is swallowed by the SDK.

This makes it extremely difficult to debug data pipeline failures, as the logs only surface a generic IOException rather than the underlying HTTP 403 Forbidden or 500 Internal Server Error.

Current Behavior :

In org.apache.beam.sdk.io.FileSystems, the matchSingleFileSpec method evaluates the MatchResult returned by the underlying match() call. If the status is not OK and not NOT_FOUND, it throws a generic exception without chaining the underlying root cause. If a GoogleJsonResponseException (or similar HTTP error) triggers the failure, it is completely lost, leaving users with only "Error matching file spec [spec]: status ERROR".

Expected Behavior :

FileSystems.matchSingleFileSpec(String spec) should include the underlying exception when it throws an IOException. The root cause should be visible in the worker's stack trace.

Issue Priority

Priority: 2 (default / most feature requests should be filed as P2)

Issue Components

• Component: Python SDK
• Component: Java SDK
• Component: Go SDK
• Component: Typescript SDK
• Component: IO connector
• Component: Beam YAML
• Component: Beam examples
• Component: Beam playground
• Component: Beam katas
• Component: Website
• Component: Infrastructure
• Component: Spark Runner
• Component: Flink Runner
• Component: Prism Runner
• Component: Twister2 Runner
• Component: Hazelcast Jet Runner
• Component: Google Cloud Dataflow Runner