alibaba/arthas · error · IllegalArgumentException

{}: command not found

Error message

{}: command not found

What it means

Thrown in createProcess when the first text token in a command line does not match any registered Command in the InternalCommandManager. The token is treated as a command name, and if no resolver provides it, Arthas reports it as unknown.

Source

Thrown at core/src/main/java/com/taobao/arthas/core/shell/system/impl/JobControllerImpl.java:158

     * @param commandManager command manager
     * @param jobId job id
     * @param term term
     * @param resultDistributor
     * @return the created process
     */
    private Process createProcess(Session session, List<CliToken> line, InternalCommandManager commandManager, int jobId, Term term, ResultDistributor resultDistributor) {
        try {
            ListIterator<CliToken> tokens = line.listIterator();
            while (tokens.hasNext()) {
                CliToken token = tokens.next();
                if (token.isText()) {
                    // check before create process
                    checkPermission(session, token);
                    Command command = commandManager.getCommand(token.value());
                    if (command != null) {
                        return createCommandProcess(command, tokens, jobId, term, resultDistributor);
                    } else {
                        throw new IllegalArgumentException(token.value() + ": command not found");
                    }
                }
            }
            throw new IllegalArgumentException();
        } catch (Exception e) {
            throw new RuntimeException(e);
        }
    }

    private boolean runInBackground(List<CliToken> tokens) {
        boolean runInBackground = false;
        CliToken last = TokenUtils.findLastTextToken(tokens);
        if (last != null && "&".equals(last.value())) {
            runInBackground = true;
            tokens.remove(last);
        }
        return runInBackground;
    }

View on GitHub (pinned to 21cf2e9ba5)

Solutions

1. Run 'help' to list all available commands and confirm the exact spelling.
2. If using an external command, ensure its jar is in ARTHAS_HOME/lib or loaded via --external-command.
3. Check the Arthas version — some commands (e.g. profiler, jfr) need a recent version or specific modules.

Example fix

// before
$ trce com.example.Service hello
// -> trce: command not found

// after
$ trace com.example.Service hello

// Verify command exists before creating a job
Command cmd = commandManager.getCommand(tokenValue);
if (cmd == null) {
    // show available commands via help
}

When it happens

Trigger: Typing a misspelled command (e.g. 'trce' instead of 'trace'), using a command that requires a plugin/external-command jar that is not on the classpath, or piping where the first segment is not a real command.

Common situations: Typos in interactive sessions. Expecting a command from an external-command module that was not installed. Version differences where a command was renamed or removed.

Related errors

• '{s}' is not a valid size. Should be numeric value followed
• '{s}' is not a valid timespan. Shoule be numeric value follo
• {optionName} must not be blank.
• {optionName} must be greater than 0.
• {optionName} is invalid: {value}

AI-assisted analysis of alibaba/arthas@21cf2e9ba5 (2026-08-14). Data as JSON: /api/errors/719e5be815f9e0b8. Report an issue: GitHub.