alibaba/DataX · error · IllegalArgumentException

File not found: ${name}

Error message

File not found: ${name}

What it means

ConfigHelper.fromClasspath(name) loads a resource from the thread-context classloader and parses it as a DataX Configuration. If getResourceAsStream returns null, Configuration.from(null) throws (NPE/IOException), and the catch rethrows IllegalArgumentException with the resource name. It is used to load bundled GDB mapping templates from the plugin jar's resources.

Source

Thrown at gdbreader/src/main/java/com/alibaba/datax/plugin/reader/gdbreader/util/ConfigHelper.java:74

        return configLabels;
    }

    static List<Configuration> splitConfig(Configuration config, List<String> labels) {
        List<Configuration> configs = new ArrayList<>();
        for (String label : labels) {
            Configuration conf = config.clone();
            conf.set(Key.LABEL, label);

            configs.add(conf);
        }
        return configs;
    }

    static Configuration fromClasspath(String name) {
        try (InputStream is = Thread.currentThread().getContextClassLoader().getResourceAsStream(name)) {
            return Configuration.from(is);
        } catch (IOException e) {
            throw new IllegalArgumentException("File not found: " + name);
        }
    }
}

View on GitHub (pinned to 80ec23d5c5)

Solutions

1. Verify the exact resource path string against the file packaged inside the jar (jar tf | grep <name>)
2. If shading, ensure resource transformers (maven-shade ServicesResourceTransformer / include patterns) keep the file
3. Set the context classloader (Thread.currentThread().setContextClassLoader(pluginClassLoader)) before invoking when embedding DataX
4. Add the missing template file under src/main/resources with the expected name

Example fix

// before
Configuration c = ConfigHelper.fromClasspath("gdb/mapping.json");
// after (fail fast with explicit existence check)
try (InputStream is = Thread.currentThread().getContextClassLoader().getResourceAsStream(name)) {
    if (is == null) throw new IllegalArgumentException("File not found: " + name);
    return Configuration.from(is);
}

static Configuration fromClasspathChecked(String name) {
    try (InputStream is = Thread.currentThread().getContextClassLoader().getResourceAsStream(name)) {
        if (is == null) throw new IllegalArgumentException("File not found: " + name);
        return Configuration.from(is);
    } catch (IOException e) {
        throw new IllegalArgumentException("File not found: " + name, e);
    }
}

catch (IllegalArgumentException e) {
    if (e.getMessage().startsWith("File not found: ")) {
        // check jar tf <plugin>.jar | grep <name>; fix resource name or packaging
    }
}

When it happens

Trigger: Calling fromClasspath with a resource name that is not on the context classloader's classpath — typo in name, resource stripped during a fat-jar/shade repackaging, or code running under a classloader that does not see the plugin jar (TCCL not set to the plugin's loader).

Common situations: Custom DataX packaging that drops resources; renaming the template file without updating the caller; running gdbreader unit tests without the resource on the test classpath; nested fat-jar where resources land under BOOT-INF and TCCL cannot see them.

Related errors

• File not found: ${name}
• Failed to cast %s to Long
• Failed to cast %s to Double
• Failed to cast %s to Boolean
• to or from missed in edge

AI-assisted analysis of alibaba/DataX@80ec23d5c5 (2026-08-14). Data as JSON: /api/errors/829c064a1a9edbf0. Report an issue: GitHub.