Route S3 store-access errors through a backend-agnostic exception

The original "Catch StoreException / N5Exception" commit caught both
backend-specific exceptions directly in the opener. On main the Fiji
opener (ZarrOpener, ome-zarr-fiji) was decoupled from the concrete
backends: it depends on the ome-zarr-imglib2 API only, and the
zarr-java backend is test-scoped, so dev.zarr.zarrjava.store.StoreException
is no longer on its compile classpath.

Introduce ome.zarr.imglib2.exceptions.StoreAccessException (mirroring the
existing PyramidLevelAccessException) and wrap store-open failures into it
inside each backend's load(): the zarr-java backend wraps StoreException,
the N5 backend wraps N5Exception thrown while opening the reader / reading
multiscale metadata. ZarrOpener now catches the backend-agnostic
StoreAccessException, keeping the decoupling intact while preserving the
original intent: report S3 auth failures, missing buckets and network
errors as a clean user-facing message instead of an unhandled exception.

The store-access test mocks the backend to throw StoreAccessException
(what a real load() now surfaces to the opener).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: stefanhahmann

ome-zarr-fiji-ui/src/test/java/ome/zarr/fijiui/open/ZarrOpenActionsTest.java

@@ -96,10 +96,10 @@
 import bdv.viewer.ViewerFrame;
 import bdv.util.BdvStackSource;
 import ij.ImagePlus;
-import dev.zarr.zarrjava.store.StoreException;
 import ome.zarr.fijiui.settings.UserScriptSettings;
 import ome.zarr.fiji.Pyramidal;
 import ome.zarr.zarrjava.ZarrJavaPyramidBackend;
+import ome.zarr.imglib2.exceptions.StoreAccessException;
 import ome.zarr.imglib2.PyramidContents;
 import ome.zarr.fiji.PyramidalBdv;
 import ome.zarr.fiji.PyramidalDataset;
@@ -703,7 +703,8 @@ void storeAccessErrorIsReportedToErrorHandler( final ZarrReaderBackend backend )
 				try ( MockedConstruction< ZarrJavaPyramidBackend > mock = mockConstruction(
 						ZarrJavaPyramidBackend.class,
 						( mockBackend, ctx ) -> when( mockBackend.load( any() ) )
-								.thenThrow( new StoreException( "Access Denied (403)" ) ) ) )
+								.thenThrow( new StoreAccessException( uri.toString(),
+										new RuntimeException( "Access Denied (403)" ) ) ) ) )
 				{
 					final ZarrOpenActions actions = new ZarrOpenActions( uri, context, settings, capturedError::set );
 					assertDoesNotThrow( () -> actions.openImage( dataset -> null, img -> null ) );

ome-zarr-fiji/src/main/java/ome/zarr/fiji/open/ZarrOpener.java

@@ -60,8 +60,7 @@
 import ome.zarr.fiji.open.exceptions.NonExistingResolutionLevelException;
 import ome.zarr.fiji.open.exceptions.NotASingleScaleImageException;
 import ome.zarr.fiji.util.BdvUtils;
-import dev.zarr.zarrjava.store.StoreException;
-import org.janelia.saalfeldlab.n5.N5Exception;
+import ome.zarr.imglib2.exceptions.StoreAccessException;
 
 /**
  * Backend-reader-agnostic opener for OME-Zarr datasets.
@@ -247,7 +246,7 @@ private Object openPyramidImage( final Supplier< Object > multiScaleOpener, fina
 			showSingleScaleNotSupported();
 			// TODO: openSingleScaleImage( singleScaleOpener ) when single-scale support is added
 		}
-		catch ( StoreException | N5Exception e )
+		catch ( StoreAccessException e )
 		{
 			showStoreAccessError( e );
 		}

ome-zarr-imglib2/src/main/java/ome/zarr/imglib2/exceptions/StoreAccessException.java

@@ -0,0 +1,49 @@
+/*-
+ * #%L
+ * OME-Zarr extras for Fiji
+ * %%
+ * Copyright (C) 2022 - 2026 SciJava developers
+ * %%
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ * #L%
+ */
+package ome.zarr.imglib2.exceptions;
+
+/**
+ * Thrown when a pyramid backend cannot access the OME-Zarr store itself —
+ * e.g. an S3 authentication failure, a missing bucket, a network error, or any
+ * other failure that prevents even opening the dataset root. Distinct from
+ * {@link PyramidLevelAccessException}, which signals a failure to read an
+ * individual resolution level after the store was reached.
+ * <p>
+ * This is a backend-agnostic wrapper so that the Fiji layer can report store
+ * access failures without depending on backend-specific exception types (e.g.
+ * zarr-java's {@code StoreException} or N5's {@code N5Exception}).
+ */
+public class StoreAccessException extends RuntimeException
+{
+
+	public StoreAccessException( final String path, final Throwable cause )
+	{
+		super( "Cannot access OME-Zarr store at: " + path, cause );
+	}
+}

ome-zarr-n5/src/main/java/ome/zarr/n5/N5PyramidBackend.java

@@ -35,6 +35,7 @@
 import net.imglib2.util.Cast;
 
 import org.janelia.saalfeldlab.n5.DataType;
+import org.janelia.saalfeldlab.n5.N5Exception;
 import org.janelia.saalfeldlab.n5.N5Reader;
 import org.janelia.saalfeldlab.n5.imglib2.N5Utils;
 import org.janelia.saalfeldlab.n5.universe.N5DatasetDiscoverer;
@@ -67,6 +68,7 @@
 import ome.zarr.imglib2.PyramidContents;
 import ome.zarr.imglib2.exceptions.MultiImageDatasetException;
 import ome.zarr.imglib2.exceptions.NotAMultiscaleImageException;
+import ome.zarr.imglib2.exceptions.StoreAccessException;
 import ome.zarr.imglib2.metadata.AxisCalibration;
 import ome.zarr.imglib2.metadata.Omero;
 
@@ -96,11 +98,24 @@ public static < T extends NativeType< T > & RealType< T > > PyramidContents< T >
 	@Override
 	public < T extends NativeType< T > & RealType< T > > PyramidContents< T > load( final URI inputUri )
 	{
-		final N5Reader reader = new N5Factory()
-				.s3Configuration( builder -> builder.region( Region.US_EAST_1 ) )
-				.openReader( inputUri.toString() );
+		final N5Reader reader;
 		final N5TreeNode treeNode = new N5TreeNode( "" );
-		final OmeNgffMetadata metadata = readMetadata( reader, treeNode, inputUri );
+		final OmeNgffMetadata metadata;
+		try
+		{
+			reader = new N5Factory()
+					.s3Configuration( builder -> builder.region( Region.US_EAST_1 ) )
+					.openReader( inputUri.toString() );
+			metadata = readMetadata( reader, treeNode, inputUri );
+		}
+		catch ( N5Exception e )
+		{
+			// Store-level failure (e.g. S3 auth failure, missing bucket, network
+			// error) before we could reach the dataset. Wrap in a backend-agnostic
+			// exception so the Fiji layer can report it without depending on N5's
+			// N5Exception type.
+			throw new StoreAccessException( inputUri.toString(), e );
+		}
 		final Multiscale multiscale = buildMultiscale( metadata, 0 );
 		final Omero omero = readOmeroMetadata( reader, treeNode );
 

ome-zarr-zarrjava/src/main/java/ome/zarr/zarrjava/ZarrJavaPyramidBackend.java

@@ -55,6 +55,7 @@
 import dev.zarr.zarrjava.store.HttpStore;
 import dev.zarr.zarrjava.store.S3Store;
 import dev.zarr.zarrjava.store.Store;
+import dev.zarr.zarrjava.store.StoreException;
 import dev.zarr.zarrjava.store.StoreHandle;
 
 import software.amazon.awssdk.auth.credentials.AnonymousCredentialsProvider;
@@ -87,6 +88,7 @@
 import ome.zarr.imglib2.exceptions.MultiImageDatasetException;
 import ome.zarr.imglib2.exceptions.NotAMultiscaleImageException;
 import ome.zarr.imglib2.exceptions.PyramidLevelAccessException;
+import ome.zarr.imglib2.exceptions.StoreAccessException;
 import ome.zarr.imglib2.PyramidBackend;
 import ome.zarr.imglib2.PyramidContents;
 import ome.zarr.imglib2.metadata.AxisCalibration;
@@ -253,7 +255,18 @@ else if ( "s3".equalsIgnoreCase( scheme ) )
 		}
 		else
 			throw new IllegalArgumentException( "Unsupported URI scheme '" + scheme + "' for OME-Zarr location: " + inputUri );
-		return openMultiscaleImageFromHandle( store.resolve() );
+		try
+		{
+			return openMultiscaleImageFromHandle( store.resolve() );
+		}
+		catch ( StoreException e )
+		{
+			// Store-level failure (e.g. S3 auth failure, missing bucket, network
+			// error) before we could reach the dataset. Wrap in a backend-agnostic
+			// exception so the Fiji layer can report it without depending on
+			// zarr-java's StoreException type.
+			throw new StoreAccessException( inputUri.toString(), e );
+		}
 	}
 
 	private MultiscaleImage openMultiscaleImageFromHandle( final StoreHandle handle )