alibaba/arthas · error · IllegalArgumentException

Error! command not permitted, try to use 'auth' command to a

Error message

Error! command not permitted, try to use 'auth' command to authenticates.

What it means

Thrown by JobControllerImpl.checkPermission when a SecurityAuthenticator is configured to require login (needLogin() returns true) but the session carries no authenticated Subject and the command being issued is not the 'auth' command itself. This is Arthas' command-level authorization gate for the shell.

Source

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

    public synchronized Job getJob(int id) {
        return jobs.get(id);
    }

    synchronized boolean removeJob(int id) {
        return jobs.remove(id) != null;
    }

    private void checkPermission(Session session, CliToken token) {
        if (ArthasBootstrap.getInstance().getSecurityAuthenticator().needLogin()) {
            // 检查session是否有 Subject
            Object subject = session.get(ArthasConstants.SUBJECT_KEY);
            if (subject == null) {
                if (token != null && token.isText() && token.value().trim().equals(ArthasConstants.AUTH)) {
                    // 执行的是auth 命令
                    return;
                }
                throw new IllegalArgumentException("Error! command not permitted, try to use 'auth' command to authenticates.");
            }
        }
    }

    @Override
    public Job createJob(InternalCommandManager commandManager, List<CliToken> tokens, Session session, JobListener jobHandler, Term term, ResultDistributor resultDistributor) {
        checkPermission(session, tokens.get(0));
        int jobId = idGenerator.incrementAndGet();
        StringBuilder line = new StringBuilder();
        for (CliToken arg : tokens) {
            line.append(arg.raw());
        }
        boolean runInBackground = runInBackground(tokens);
        Process process = createProcess(session, tokens, commandManager, jobId, term, resultDistributor);
        process.setJobId(jobId);
        JobImpl job = new JobImpl(jobId, this, process, line.toString(), runInBackground, session, jobHandler);
        jobs.put(jobId, job);
        return job;

View on GitHub (pinned to 21cf2e9ba5)

Solutions

1. Run 'auth <your-token>' as the first command in the session, where the token matches arthas.properties 'arthas.authToken' or the --auth-token flag.
2. Disable authentication for local debugging by removing the authToken configuration.
3. In HTTP API workflows, pass the Authorization header (configured auth) so the session is pre-authenticated.
4. Verify the token value matches exactly — a wrong token silently leaves subject null.

Example fix

$ telnet 127.0.0.1 3658
# before:
trace com.example.Service hello
# -> Error! command not permitted, try to use 'auth' command to authenticates.

# after:
auth mySecretToken
trace com.example.Service hello

// Before issuing commands, check if auth is needed and whether session is authenticated
if (ArthasBootstrap.getInstance().getSecurityAuthenticator().needLogin()) {
    Object subject = session.get(ArthasConstants.SUBJECT_KEY);
    if (subject == null) {
        // send 'auth <token>' first
    }
}

When it happens

Trigger: A user opens a telnet/http session and types any diagnostic command (e.g. 'trace', 'watch') before running 'auth <password>'. The SecurityAuthenticator was enabled via -Darthas.authToken or arthas.properties, so every non-auth command is blocked until login.

Common situations: Production deployments that secure Arthas with a token. Forgetting to authenticate after connecting via telnet or the web console. Automation scripts that open a session but skip the auth step.

Understand the failure class

• Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

• Bad zip entry: {currentEntry}
• SessionId is required for this operation
• Failed to create temporary session
• Session not found: {sessionId}
• 文件不在允许目录白名单内: ${requestedPath}

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