What causes "File not found: ${name}" in alibaba/DataX?

Verify the exact resource name (case-sensitive, no leading slash mismatch) matches what is packaged.

alibaba/DataX · error · IllegalArgumentException

File not found: ${name}

Error message

File not found: ${name}

What it means

IllegalArgumentException thrown by ConfigHelper.fromClasspath when Configuration.from(is) raises IOException while loading a resource from the thread-context classloader. In practice this fires both when the resource name is not found (getResourceAsStream returns null, causing a NullPointerException/IOException downstream) and when the stream cannot be read.

Source

Thrown at gdbwriter/src/main/java/com/alibaba/datax/plugin/writer/gdbwriter/util/ConfigHelper.java:60

     * @return the target configuration object of type T
     */
    static <T> T getConfig(final Configuration conf, final String key, final Class<T> cls) {
        final JSONObject j = (JSONObject)conf.get(key);
        return JSON.toJavaObject(j, cls);
    }

    /**
     * Create a configuration from the specified file on the classpath.
     * 
     * @param name
     *            file name
     * @return Configuration instance.
     */
    static Configuration fromClasspath(final String name) {
        try (final InputStream is = Thread.currentThread().getContextClassLoader().getResourceAsStream(name)) {
            return Configuration.from(is);
        } catch (final IOException e) {
            throw new IllegalArgumentException("File not found: " + name);
        }
    }
}

View on GitHub (pinned to 80ec23d5c5)

Solutions

Verify the exact resource name (case-sensitive, no leading slash mismatch) matches what is packaged.
Ensure the file is included in the plugin distribution: check the jar contents (jar tf) or the plugin resources directory next to the jar.
If running inside a container/test, confirm the thread-context classloader can see the resource; try the plugin's own classloader as a fallback.

Defensive patterns

Strategy: validation

Validate before calling

if (Thread.currentThread().getContextClassLoader().getResource(name) == null) {
    throw new FileNotFoundException("resource not on classpath: " + name);
}

Try / catch

try {
    cfg = ConfigHelper.fromClasspath(name);
} catch (IllegalArgumentException e) {
    // surface which jar/dir was searched; fail fast with packaging hint
}

Prevention

Add a packaging test asserting required resources exist in the built jar (jar tf check in CI).
Keep resource names in one constant class to avoid typos.
Test plugins by loading them through the same classloader DataX uses in production.

When it happens

Trigger: Calling fromClasspath(name) where 'name' is not present on the plugin classpath — e.g. a mapper/template file expected inside the gdbwriter plugin jar or plugin directory that is missing, misnamed, or not copied during packaging.

Common situations: Custom plugin build that forgot to include a resources file; deploying only the compiled jar without the resources directory; typo in the resource file name; running tests where the thread-context classloader differs from the plugin classloader.

Related errors

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