What causes "Location does not exist: %s" in apache/iceberg?

Verify the full gs:// URI — bucket name and object path — actually exists (gsutil ls)

apache/iceberg · error · NotFoundException

Location does not exist: %s

Error message

Location does not exist: %s

What it means

GCSExceptionUtil.throwNotFoundIfNotPresent converts a GCS StorageException with code 404 into Iceberg's NotFoundException with 'Location does not exist: %s' carrying the gs:// URI of the BlobId. It signals the requested GCS object simply does not exist.

Source

Thrown at gcp/src/main/java/org/apache/iceberg/gcp/gcs/GCSExceptionUtil.java:32

 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied.  See the License for the
 * specific language governing permissions and limitations
 * under the License.
 */
package org.apache.iceberg.gcp.gcs;

import com.google.cloud.storage.BlobId;
import com.google.cloud.storage.StorageException;
import java.io.IOException;
import org.apache.iceberg.exceptions.NotFoundException;

final class GCSExceptionUtil {
  private GCSExceptionUtil() {}

  static void throwNotFoundIfNotPresent(IOException ioException, BlobId blobId) {
    if (ioException.getCause() instanceof StorageException storageException
        && storageException.getCode() == 404) {
      throw new NotFoundException(ioException, "Location does not exist: %s", blobId.toGsUtilUri());
    }
  }
}

View on GitHub (pinned to 86d9c8fc54)

Solutions

Verify the full gs:// URI — bucket name and object path — actually exists (gsutil ls)
Check bucket lifecycle/retention rules that may delete objects unexpectedly
Confirm you are pointing at the intended environment/project and warehouse location
Catch NotFoundException in callers and handle missing-object cases explicitly

Example fix

// before
GCSExceptionUtil.throwNotFoundIfNotPresent(ioe, blobId);
// after (caller side)
try {
  fileIO.newInputFile(location);
} catch (NotFoundException e) {
  LOG.error("Object missing at {} — check path and lifecycle rules", location);
  throw e;
}

Defensive patterns

Strategy: try-catch

Validate before calling

// check existence before operating
Blob blob = storage.get(blobId);
if (blob == null) { throw new NotFoundException("Object absent: " + blobId.toGsUtilUri()); }

Try / catch

try { fileIO.newInputFile(gsUri).newStream(); } catch (NotFoundException e) { LOG.warn("GCS object missing: {}", gsUri); /* handle absence */ }

Prevention

Validate gs:// paths and bucket names in config
Watch for lifecycle-rule deletions
Distinguish dev/prod buckets per environment

When it happens

Trigger: An IO operation (read/exists/delete via GCS FileIO) fails with StorageException code 404 for the blob at the given BlobId.

Common situations: Typo in the warehouse/bucket path, object deleted by a lifecycle rule or another job, wrong environment (dev vs prod bucket), or reading a table whose metadata file was removed.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

AI-assisted analysis of apache/iceberg@86d9c8fc54 (2026-09-12). Data as JSON: /api/errors/df37af25877477de. Report an issue: GitHub.