apache/hadoop · error · IOException

This job has exceeded the maximum size of a single submitted

Error message

This job has exceeded the maximum size of a single submitted resource (Max: {}MB, Violating resource: {}).

What it means

The per-resource LimitChecker check: it tracks the largest single file seen (currentMaxSizeOfFileBytes) while walking staged resources, and if one resource exceeds the configured per-item cap (mapreduce.job.cache.limit.max-single-resource-mb, MRJobConfig.MAX_SINGLE_RESOURCE_MB; default 0 = unlimited), addFile throws IOException('This job has exceeded the maximum size of a single submitted resource (Max: <N>MB, Violating resource: <path>).') — conveniently naming the offending file.

Source

Thrown at hadoop-mapreduce-project/hadoop-mapreduce-client/hadoop-mapreduce-client-core/src/main/java/org/apache/hadoop/mapreduce/JobResourceUploader.java:607

      totalSizeBytes += fileSizeBytes;
      if (fileSizeBytes > currentMaxSizeOfFileBytes) {
        currentMaxSizeOfFileBytes = fileSizeBytes;
      }

      if (totalConfigSizeBytes > 0 && totalSizeBytes > totalConfigSizeBytes) {
        throw new IOException(MAX_TOTAL_RESOURCE_MB_ERR_MSG + " (Max: "
            + maxSizeMB + "MB).");
      }

      if (maxNumOfResources > 0 &&
          totalNumberOfResources > maxNumOfResources) {
        throw new IOException(MAX_RESOURCE_ERR_MSG + " (Max: "
            + maxNumOfResources + ").");
      }

      if (totalConfigSizeOfResourceBytes > 0
          && currentMaxSizeOfFileBytes > totalConfigSizeOfResourceBytes) {
        throw new IOException(MAX_SINGLE_RESOURCE_MB_ERR_MSG + " (Max: "
            + maxSizeOfResourceMB + "MB, Violating resource: " + p + ").");
      }
    }
  }

  /**
   * Recursively explore the given path and enforce the limits for resource
   * localization. This method assumes that there are no symlinks in the
   * directory structure.
   */
  private void explorePath(Configuration job, Path p,
      LimitChecker limitChecker, Map<URI, FileStatus> statCache)
      throws IOException {
    Path pathWithScheme = p;
    if (!pathWithScheme.toUri().isAbsolute()) {
      // the path does not have a scheme, so we assume it is a path from the
      // local filesystem
      FileSystem localFs = FileSystem.getLocal(job);

View on GitHub (pinned to 2add963021)

Solutions

1. Move the oversized artifact out of the distributed cache: upload it to HDFS once and read it by Path in the tasks
2. Split or shrink the offending resource named in the message (compress, trim unused deps from the shaded jar)
3. With admin approval, raise mapreduce.job.cache.limit.max-single-resource-mb above the size reported in the error
4. Add a build-time check that fails when any shipped artifact exceeds the cluster's per-item cap

Example fix

# before
hadoop jar app.jar Driver -files "model-2GB.bin" in out
# IOException: exceeded the maximum size of a single submitted resource
# (Max: 512MB, Violating resource: /user/me/.staging/job_.../files/model-2GB.bin)

# after
hdfs dfs -put model-2GB.bin /data/models/
hadoop jar app.jar Driver -Dmodel.path=/data/models/model-2GB.bin in out

// fail on any single oversized artifact before submit
long cap = conf.getLong("mapreduce.job.cache.limit.max-single-resource-mb", 0) * 1024L * 1024L;
if (cap > 0) {
  for (Path p : shippedPaths) {
    long size = p.getFileSystem(conf).getFileStatus(p).getLen();
    if (size > cap) {
      throw new IllegalStateException(p + " is " + (size / 1048576) + "MB; cap is " + (cap / 1048576) + "MB — move it to HDFS and read by path");
    }
  }
}

When it happens

Trigger: Including one large artifact (ML model, dictionary, native library bundle) in -files/-archives while a single-resource cap is configured; an uber jar grown past the cap after adding dependencies; a data file accidentally shipped as code.

Common situations: Clusters capping per-item localization to protect NodeManager disk; model-serving jobs shipping big binaries; builds whose shaded jar slowly grows release over release until it crosses the limit.

Related errors

• This job has exceeded the maximum size of submitted resource
• This job has exceeded the maximum number of submitted resour
• Error parsing local resource path. Path was not able to be c
• Resource type PATTERN is not implemented yet. {}
• Invalid specification for distributed-cache artifacts of typ

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