apache/flink · error · IllegalArgumentException

Error parsing arguments '%s' on '%s'. Please prefix keys wit

Error message

Error parsing arguments '%s' on '%s'. Please prefix keys with -- or -.

What it means

Utils.getKeyFromArgs expects every CLI-style key token to start with '--' (long) or '-' (short). A token at the given index that starts with neither is rejected with this IllegalArgumentException showing the full args array and the offending token, since the parser cannot tell where the key ends and a value begins.

Source

Thrown at flink-core/src/main/java/org/apache/flink/util/Utils.java:354

        return Optional.ofNullable(factory);
    }

    /**
     * Get the key from the given args. Keys have to start with '-' or '--'. For example, --key1
     * value1 -key2 value2.
     *
     * @param args all given args.
     * @param index the index of args to be parsed.
     * @return the key of the given arg.
     */
    public static String getKeyFromArgs(String[] args, int index) {
        String key;
        if (args[index].startsWith("--")) {
            key = args[index].substring(2);
        } else if (args[index].startsWith("-")) {
            key = args[index].substring(1);
        } else {
            throw new IllegalArgumentException(
                    String.format(
                            "Error parsing arguments '%s' on '%s'. Please prefix keys with -- or -.",
                            Arrays.toString(args), args[index]));
        }

        if (key.isEmpty()) {
            throw new IllegalArgumentException(
                    "The input " + Arrays.toString(args) + " contains an empty argument");
        }

        return key;
    }

    /** Private constructor to prevent instantiation. */
    private Utils() {
        throw new RuntimeException();
    }
}

View on GitHub (pinned to 2f3c205e92)

Solutions

1. Add the '--' prefix to the offending key token shown in the message.
2. Check argument order: '-k value' not 'value -k'; ensure options declared as flag-only are not followed by an expected value token.
3. Escape/quote dashes in shell scripts so they are not swallowed as options.

Example fix

# before
flink run app.jar input /data

# after
flink run app.jar --input /data

static boolean isKeyToken(String s) { return s.startsWith("--") && s.length() > 2 || s.startsWith("-") && s.length() > 1; }
for (String a : args) if (needsPrefix(a) && !isKeyToken(a)) throw new IllegalArgumentException("Missing -- prefix: " + a);

When it happens

Trigger: Calling getKeyFromArgs(args, i) where args[i] is a bare word like "input" instead of "--input", or a value token reached while the parser expected a key (option value consumed and next token is unprefixed).

Common situations: Wrong argument order in bin/flink CLI invocations (value before key), shell scripts dropping the leading dashes, options that take no value followed by another unprefixed token, programmatic use of the utility with unnormalized args.

Related errors

• The input ${args} contains an empty argument
• Cannot parse ApplicationID from "{hexString}". The expected
• Cannot parse JobID from "{hexString}". The expected format i
• Unsupported serializer type %s for %s
• The input {} contains an empty argument

AI-assisted analysis of apache/flink@2f3c205e92 (2026-08-14). Data as JSON: /api/errors/fbedcc322070377f. Report an issue: GitHub.