{"record":{"id":"5e1d1f6af9dc2d1a","repo":"apache/hadoop","slug":"item-not-found-s","errorCode":null,"errorMessage":"Item not found: %s","messagePattern":"Item not found: (.+?)","errorType":"exception","errorClass":"FileNotFoundException","httpStatus":null,"severity":"error","filePath":"hadoop-cloud-storage-project/hadoop-gcp/src/main/java/org/apache/hadoop/fs/gs/GoogleCloudStorageClientReadChannel.java","lineNumber":569,"sourceCode":"        blobReadOptions.add(BlobSourceOption.generationMatch(blobId.getGeneration()));\n      }\n\n      // TODO: Add support for encryptionKey\n      return blobReadOptions.toArray(new BlobSourceOption[blobReadOptions.size()]);\n    }\n\n    private boolean isFooterRead() {\n      return objectSize - currentPosition <= config.getMinRangeRequestSize();\n    }\n  }\n\n  private static void validate(GoogleCloudStorageItemInfo itemInfo) throws IOException {\n    checkNotNull(itemInfo, \"itemInfo cannot be null\");\n    StorageResourceId resourceId = itemInfo.getResourceId();\n    checkArgument(\n        resourceId.isStorageObject(), \"Can not open a non-file object for read: %s\", resourceId);\n    if (!itemInfo.exists()) {\n      throw new FileNotFoundException(String.format(\"Item not found: %s\", resourceId));\n    }\n  }\n\n  private IOException convertError(Exception error) {\n    String msg = String.format(\"Error reading '%s'\", resourceId);\n    switch (ErrorTypeExtractor.getErrorType(error)) {\n    case NOT_FOUND:\n      return createFileNotFoundException(\n          resourceId.getBucketName(), resourceId.getObjectName(), new IOException(msg, error));\n    case OUT_OF_RANGE:\n      return (IOException) new EOFException(msg).initCause(error);\n    default:\n      return new IOException(msg, error);\n    }\n  }\n\n  /** Validates that the given position is valid for this channel. */\n  private void validatePosition(long position) throws IOException {","sourceCodeStart":551,"sourceCodeEnd":587,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-cloud-storage-project/hadoop-gcp/src/main/java/org/apache/hadoop/fs/gs/GoogleCloudStorageClientReadChannel.java#L551-L587","documentation":"The client read channel's static validate(itemInfo) throws FileNotFoundException(\"Item not found: <resourceId>\") when opening a channel for an object whose GoogleCloudStorageItemInfo.exists() is false. It first asserts the id is a storage object (not a bucket or root). This runs at open time, before any bytes are requested.","triggerScenarios":"gcs.open(itemInfo) / GHFS open() on a path that was deleted, never existed, or whose pinned generation no longer exists; opening from itemInfo taken from a stale listing or cache after the object was removed.","commonSituations":"Races between concurrent jobs (output committer cleanup deleting temp files while another task reads them); stale directory listings; typo'd or wrongly-encoded paths; objects deleted and recreated while a reader pinned the old generation.","solutions":["Re-stat the path with getItemInfo immediately before opening and handle absence in application logic.","For rename/commit races, use an idempotent output committer and serialize producer/cleanup of the same paths.","If pinning generations intentionally, catch FileNotFoundException and re-fetch item info for the live generation.","Fix path construction (URI encoding, leading slashes, case)."],"exampleFix":"// before\ntry (SeekableByteChannel ch = gcs.open(itemInfo)) { ... } // FileNotFoundException\n\n// after\nGoogleCloudStorageItemInfo fresh = gcs.getItemInfo(itemInfo.getResourceId());\nif (!fresh.exists()) {\n  return; // or throw domain-specific 'input vanished' error\n}\ntry (SeekableByteChannel ch = gcs.open(fresh)) { ... }","handlingStrategy":"validation","validationCode":"GoogleCloudStorageItemInfo fresh = gcs.getItemInfo(resourceId);\nif (!fresh.exists()) {\n  throw new MissingInputException(resourceId); // domain-specific, actionable\n}\ntry (SeekableByteChannel ch = gcs.open(fresh)) { /* read */ }","typeGuard":null,"tryCatchPattern":"catch (FileNotFoundException e) {\n  // input vanished (deleted/moved concurrently): re-stat to distinguish typo vs race\n  if (!gcs.getItemInfo(resourceId).exists()) throw e;\n  /* else stale info: retry open with fresh item info */\n}","preventionTips":["Stat with getItemInfo immediately before open instead of trusting cached listings.","Give each path a single owner (producer or deleter) to avoid delete/read races.","Surface file-not-found with the full gs:// URI so path typos are easy to spot."],"tags":["gcs","filenotfound","open","read","race-condition"],"backgroundTag":"object-not-found","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}