What causes "File not found %s" in apache/hadoop?

Verify the key exists before reading: ObjectInfo info = storage.objectStatus(key); if (info == null) handle-missing

apache/hadoop · error · RuntimeException

File not found %s

Error message

File not found %s

What it means

FileStore.get(key, offset, limit) maps the object key to a local file under the store root and throws this RuntimeException when that file does not exist. Unlike most filesystem APIs it is a plain RuntimeException (not FileNotFoundException), because the FileStore emulates an object store on local disk and treats a missing backing file as an unexpected invariant violation.

Source

Thrown at hadoop-cloud-storage-project/hadoop-tos/src/main/java/org/apache/hadoop/fs/tosfs/object/FileStore.java:156

      return key;
    }
  }

  private static String decode(String key) {
    try {
      return URLDecoder.decode(key, "UTF-8");
    } catch (UnsupportedEncodingException e) {
      LOG.warn("failed to decode key: {}", key);
      return key;
    }
  }

  @Override
  public ObjectContent get(String key, long offset, long limit) {
    Preconditions.checkArgument(!Strings.isNullOrEmpty(key), "Key should not be empty.");
    File file = path(encode(key)).toFile();
    if (!file.exists()) {
      throw new RuntimeException(String.format("File not found %s", file.getAbsolutePath()));
    }

    Range range = ObjectUtils.calculateRange(offset, limit, file.length());
    try (FileInputStream in = new FileInputStream(file)) {
      in.skip(range.off());
      byte[] bs = new byte[(int) range.len()];
      in.read(bs);

      byte[] fileChecksum = getFileChecksum(file.toPath());
      return new ObjectContent(fileChecksum, new ByteArrayInputStream(bs));
    } catch (IOException e) {
      throw new RuntimeException(e);
    }
  }

  @Override
  public byte[] put(String key, InputStreamProvider streamProvider, long contentLength) {
    Preconditions.checkArgument(!Strings.isNullOrEmpty(key), "Key should not be empty.");

View on GitHub (pinned to 2add963021)

Solutions

Verify the key exists before reading: ObjectInfo info = storage.objectStatus(key); if (info == null) handle-missing
Confirm every process using the store resolves the same root (same fs.filestore.endpoint / FILE_STORAGE_ROOT env value)
Eliminate concurrent deletes of the key between listing and reading, or retry the read
Do not pre-encode/decode the key yourself — pass the same raw key string that was used with put()/uploadPart()

Example fix

// before
ObjectContent c = storage.get(key, 0, -1); // RuntimeException: File not found ...
// after
if (storage.objectStatus(key) == null) {
  throw new FileNotFoundException("object missing: " + key);
}
ObjectContent c = storage.get(key, 0, -1);

Defensive patterns

Strategy: validation

Validate before calling

if (storage.objectStatus(key) == null) {
  // object absent: handle before calling get()
  throw new java.io.FileNotFoundException("object missing: " + key);
}
ObjectContent content = storage.get(key, offset, limit);

Try / catch

try {
  ObjectContent content = storage.get(key, offset, limit);
} catch (RuntimeException e) {
  if (e.getMessage() != null && e.getMessage().startsWith("File not found")) {
    throw new java.io.FileNotFoundException(key); // normalize to the conventional signal
  }
  throw e;
}

Prevention

Check existence with objectStatus(key) (returns null when absent) before get() on cold paths
Use one store root per test/process; never share keys across roots configured differently
Pass the identical raw key string used for put() — do not URL-encode/decode keys yourself
Serialize delete/read access to a key, or tolerate FileNotFoundException via retry-once logic

When it happens

Trigger: storage.get(key, ...) after the object was deleted, for a key never written, when a different fs.filestore.endpoint/FILE_STORAGE_ROOT was used by the writing process, or when the key was URL-encoded differently by the writer (the store encodes keys onto paths).

Common situations: Test suites where each test uses a fresh temp root but a cached ObjectStorage instance still points at the old root; concurrent tests deleting shared keys; passing a URI-escaped key to get() when put() stored the unescaped form (or vice versa).

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

AI-assisted analysis of apache/hadoop@2add963021 (2026-08-22). Data as JSON: /api/errors/587b72d90045cc0f. Report an issue: GitHub.