elastic/elasticsearch · warning · UserException

USAGE

USAGE

Error message

Positional arguments not allowed, found ${options.nonOptionArguments()}

What it means

Thrown by ServerCli.execute() at the very start when the parsed command line contains non-option (positional) arguments. The elasticsearch command accepts only named flags (--daemonize, --pidfile, etc.); bare positional tokens are rejected as usage errors.

Source

Thrown at distribution/tools/server-cli/src/main/java/org/elasticsearch/server/cli/ServerCli.java:82

        versionOption = parser.acceptsAll(Arrays.asList("V", "version"), "Prints Elasticsearch version information and exits");
        daemonizeOption = parser.acceptsAll(Arrays.asList("d", "daemonize"), "Starts Elasticsearch in the background")
            .availableUnless(versionOption);
        pidfileOption = parser.acceptsAll(Arrays.asList("p", "pidfile"), "Creates a pid file in the specified path on start")
            .availableUnless(versionOption)
            .withRequiredArg()
            .withValuesConvertedBy(new PathConverter());
        quietOption = parser.acceptsAll(Arrays.asList("q", "quiet"), "Turns off standard output/error streams logging in console")
            .availableUnless(versionOption)
            .availableUnless(daemonizeOption);
        enrollmentTokenOption = parser.accepts("enrollment-token", "An existing enrollment token for securely joining a cluster")
            .availableUnless(versionOption)
            .withRequiredArg();
    }

    @Override
    public void execute(Terminal terminal, OptionSet options, Environment env, ProcessInfo processInfo) throws Exception {
        if (options.nonOptionArguments().isEmpty() == false) {
            throw new UserException(ExitCodes.USAGE, "Positional arguments not allowed, found " + options.nonOptionArguments());
        }
        if (options.has(versionOption)) {
            printVersion(terminal);
            return;
        }

        validateConfig(options, env);

        var secureSettingsLoader = secureSettingsLoader(processInfo);

        try (
            var loadedSecrets = secureSettingsLoader.load(env, terminal);
            var password = (loadedSecrets.password().isPresent()) ? loadedSecrets.password().get() : new SecureString(new char[0]);
        ) {
            SecureSettings secrets = loadedSecrets.secrets();
            if (secureSettingsLoader.supportsSecurityAutoConfiguration()) {
                env = autoConfigureSecurity(terminal, options, processInfo, env, password);
                // reload or create the secrets

View on GitHub (pinned to db6a809a66)

Solutions

1. Remove all positional arguments; use only named flags (e.g. -d, -q, -p <pidfile>, -E <setting>=<value>).
2. If you meant to pass a setting, use -E cluster.name=mycluster.
3. Run bin/elasticsearch --help to see accepted options.

Example fix

# before
bin/elasticsearch start

# after
bin/elasticsearch

if (!options.nonOptionArguments().isEmpty()) {
    throw new IllegalArgumentException(
        "Positional args not allowed: " + options.nonOptionArguments()
            + " — use named flags like -E key=value.");
}

When it happens

Trigger: Running bin/elasticsearch with a trailing positional token, e.g. bin/elasticsearch start or bin/elasticsearch foo bar.

Common situations: Assuming a 'start' subcommand like systemd/init scripts; passing a config file path positionally instead of via -E path.conf=...; copy-pasting a command from outdated docs.

Related errors

• USAGE
• USAGE
• Unknown secure settings source [${source}]
• CONFIG
• Directory for entitlement bridge jar does not exist: ${dir}

AI-assisted analysis of elastic/elasticsearch@db6a809a66 (2026-08-12). Data as JSON: /api/errors/7089e46ab705a50d. Report an issue: GitHub.