apache/hadoop · error · IllegalArgumentException

Could not locate MapReduce framework name '{}' in mapreduce.

Error message

Could not locate MapReduce framework name '{}' in mapreduce.application.classpath

What it means

After deriving the framework name from mapreduce.application.framework.path (URI fragment, else file base name), MRApps checks that this name appears as a substring of at least one entry of mapreduce.application.classpath while building the container classpath. If no classpath entry contains the framework name, it throws IllegalArgumentException — the bundle would be localized but never loadable, since nothing puts it on the classpath.

Source

Thrown at hadoop-mapreduce-project/hadoop-mapreduce-client/hadoop-mapreduce-client-common/src/main/java/org/apache/hadoop/mapreduce/v2/util/MRApps.java:230

        MRApps.addToEnvironment(environment, Environment.CLASSPATH.name(),
          c.trim(), conf);
      }
    }

    boolean foundFrameworkInClasspath = (frameworkName == null);
    for (String c : conf.getStrings(MRJobConfig.MAPREDUCE_APPLICATION_CLASSPATH,
        crossPlatform ?
            StringUtils.getStrings(MRJobConfig.DEFAULT_MAPREDUCE_CROSS_PLATFORM_APPLICATION_CLASSPATH)
            : StringUtils.getStrings(MRJobConfig.DEFAULT_MAPREDUCE_APPLICATION_CLASSPATH))) {
      MRApps.addToEnvironment(environment, Environment.CLASSPATH.name(),
        c.trim(), conf);
      if (!foundFrameworkInClasspath) {
        foundFrameworkInClasspath = c.contains(frameworkName);
      }
    }

    if (!foundFrameworkInClasspath) {
      throw new IllegalArgumentException(
          "Could not locate MapReduce framework name '" + frameworkName
          + "' in " + MRJobConfig.MAPREDUCE_APPLICATION_CLASSPATH);
    }
    // TODO: Remove duplicates.
  }
  
  @SuppressWarnings("deprecation")
  public static void setClasspath(Map<String, String> environment,
      Configuration conf) throws IOException {
    boolean userClassesTakesPrecedence = 
      conf.getBoolean(MRJobConfig.MAPREDUCE_JOB_USER_CLASSPATH_FIRST, false);

    String classpathEnvVar =
      conf.getBoolean(MRJobConfig.MAPREDUCE_JOB_CLASSLOADER, false)
        ? Environment.APP_CLASSPATH.name() : Environment.CLASSPATH.name();

    MRApps.addToEnvironment(environment,
      classpathEnvVar, crossPlatformifyMREnv(conf, Environment.PWD), conf);

View on GitHub (pinned to 2add963021)

Solutions

Add a classpath entry containing the framework name, e.g. append $PWD/mr-framework/* or $PWD/mr-framework.zip to mapreduce.application.classpath
Make the fragment in the framework path exactly match the name used in the classpath entry
If you did not intend a custom framework, remove mapreduce.application.framework.path entirely

Example fix

# before
mapreduce.application.framework.path = hdfs://nn/dist/mr-framework.zip#mr-framework
mapreduce.application.classpath = $HADOOP_MAPRED_HOME/*

# after
mapreduce.application.classpath = $HADOOP_MAPRED_HOME/*,$PWD/mr-framework/*

Defensive patterns

Strategy: validation

Validate before calling

String fw = conf.get("mapreduce.application.framework.path", "");
if (!fw.isEmpty()) {
  java.net.URI u = new URI(fw);
  String name = u.getFragment() != null ? u.getFragment() : new Path(u).getName();
  boolean found = Arrays.stream(conf.getStrings("mapreduce.application.classpath"))
      .anyMatch(c -> c.contains(name));
  if (!found) throw new ConfigException("framework name '" + name + "' missing from classpath config");
}

Try / catch

try {
  MRApps.setMRFrameworkClasspath(env, conf);
} catch (IllegalArgumentException e) {
  throw new IllegalStateException("mapreduce.application.framework.path name must "
      + "appear in mapreduce.application.classpath", e);
}

Prevention

Whenever you set mapreduce.application.framework.path, add a matching entry ($PWD/<name>/*) to mapreduce.application.classpath
Keep the fragment name and the classpath token byte-identical (watch case and version suffixes)
Unset the framework path entirely when the default MR runtime is intended

When it happens

Trigger: Configuring mapreduce.application.framework.path=hdfs://nn/x/mr-framework.zip (name 'mr-framework') while mapreduce.application.classpath uses only default entries like $HADOOP_MAPRED_HOME/* that do not contain that name; mismatch between the fragment name and the classpath entry spelling.

Common situations: Standing up an alternative MR framework (e.g. a custom/forked MR runtime) and forgetting to add it to mapreduce.application.classpath; renaming the framework jar without updating the classpath; case or version-suffix mismatches between fragment and classpath token.

Related errors

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