jenkinsci/jenkins · error · IllegalStateException

Node ' already exists

Error message

Node ' already exists

What it means

`CreateNodeCommand.run()` deserializes a Node from stdin, optionally overrides its name from the NODE argument, then checks `jenkins.getNode(newNode.getNodeName()) != null`. If a node with that name exists, IllegalStateException 'Node '<name>' already exists' is thrown before `addNode`. Node names must be unique.

Source

Thrown at core/src/main/java/hudson/cli/CreateNodeCommand.java:64

        return Messages.CreateNodeCommand_ShortDescription();
    }

    @Override
    protected int run() throws Exception {

        final Jenkins jenkins = Jenkins.get();
        jenkins.checkPermission(Computer.CREATE);

        final Node newNode = (Node) Jenkins.XSTREAM2.fromXML(stdin);

        if (nodeName != null) {

            // Using deprecated method but it's contract is preserved
            newNode.setNodeName(nodeName);
        }

        if (jenkins.getNode(newNode.getNodeName()) != null) {
            throw new IllegalStateException("Node '" + newNode.getNodeName() + "' already exists");
        }

        jenkins.addNode(newNode);

        return 0;
    }

}

View on GitHub (pinned to 2e228ff40b)

Solutions

1. Delete the existing node first: `java -jar jenkins-cli.jar delete-node <name>`, then create.
2. Choose a different node name (pass a unique NODE argument or edit the XML's name).
3. In scripts, check `jenkins.getNode(name) == null` before creating.

Example fix

// before:
//   java -jar jenkins-cli.jar create-node agent1 < agent.xml  // agent1 exists
//   -> IllegalStateException: Node 'agent1' already exists
//
// after: delete then recreate, or use a new name
//   java -jar jenkins-cli.jar delete-node agent1
//   java -jar jenkins-cli.jar create-node agent1 < agent.xml

// Ensure node name is free before create-node
if (jenkins.getNode(newNode.getNodeName()) != null) {
    throw new IllegalStateException("Node '" + newNode.getNodeName() + "' already exists");
}

When it happens

Trigger: Running `java -jar jenkins-cli.jar create-node <name> < node.xml` (or create-node with a name inside the XML) where a node/agent with that name already exists.

Common situations: Re-running create-node after a prior success; importing agent XML whose name collides; re-adding a previously removed-but-not-deleted agent.

Related errors

• Error occurred while performing this command, see previous s
• Job ' already exists
• View ' already exists
• Job ' already exists
• Unknown ItemGroup

AI-assisted analysis of jenkinsci/jenkins@2e228ff40b (2026-08-14). Data as JSON: /api/errors/12608929029906a3. Report an issue: GitHub.