apache/dolphinscheduler · error · ServiceException

QUEUE_NAME_EXIST

QUEUE_NAME_EXIST

Error message

QUEUE_NAME_EXIST: queue name {queueName} already exists

What it means

QUEUE_NAME_EXIST is thrown by validQueue() when the queue display name already exists. checkQueueNameExist(queue.getQueueName()) returns true, so a new queue with this name would break name uniqueness. Raised from createQueue, verifyQueue, and createQueueIfNotExists.

Source

Thrown at dolphinscheduler-api/src/main/java/org/apache/dolphinscheduler/api/service/impl/QueueServiceImpl.java:81

    private UserDao userDao;

    @Autowired
    private TenantDao tenantDao;

    /**
     * Check the queue new object valid or not
     *
     * @param queue The queue object want to create
     */
    private void validQueue(Queue queue) throws ServiceException {
        if (StringUtils.isEmpty(queue.getQueue())) {
            throw new ServiceException(Status.REQUEST_PARAMS_NOT_VALID_ERROR, Constants.QUEUE);
        } else if (StringUtils.isEmpty(queue.getQueueName())) {
            throw new ServiceException(Status.REQUEST_PARAMS_NOT_VALID_ERROR, Constants.QUEUE_NAME);
        } else if (checkQueueExist(queue.getQueue())) {
            throw new ServiceException(Status.QUEUE_VALUE_EXIST, queue.getQueue());
        } else if (checkQueueNameExist(queue.getQueueName())) {
            throw new ServiceException(Status.QUEUE_NAME_EXIST, queue.getQueueName());
        }
    }

    /**
     * Check queue update object valid or not
     *
     * @param existsQueue The exists queue object
     * @param updateQueue The queue object want to update
     */
    private void updateQueueValid(Queue existsQueue, Queue updateQueue) throws ServiceException {
        // Check the exists queue and the necessary of update operation, in not exist checker have to use updateQueue to
        // avoid NPE
        if (Objects.isNull(existsQueue)) {
            throw new ServiceException(Status.QUEUE_NOT_EXIST, updateQueue.getQueue());
        } else if (Objects.equals(existsQueue, updateQueue)) {
            throw new ServiceException(Status.NEED_NOT_UPDATE_QUEUE);
        }
        // Check the update queue parameters

View on GitHub (pinned to 02eac45a1b)

Solutions

  1. Pick a unique queueName
  2. Verify the name via verifyQueue before creating
  3. If updating, use updateQueue instead of create

Example fix

// before
queueService.createQueue(loginUser, "low", "DefaultQueue"); // name taken
// after
queueService.createQueue(loginUser, "low", "LowPriorityQueue");
Defensive patterns

Strategy: try-catch

Validate before calling

boolean nameTaken = !queueService.verifyQueue(loginUser, queue, queueName).isSuccess(); // QUEUE_NAME_EXIST means taken

Try / catch

try {
    queueService.createQueue(loginUser, queue, queueName);
} catch (ServiceException e) {
    if (e.getCode() == Status.QUEUE_NAME_EXIST.getCode()) { /* pick another name or reuse */ }
    throw e;
}

Prevention

When it happens

Trigger: createQueue with a queueName matching an existing queue row; verifyQueue probing a taken name; createQueueIfNotExists when a different queue row already uses the same name.

Common situations: Renaming a queue to a name another queue already uses; seeding the same queue set twice; case-sensitivity surprises where names differ only by case depending on DB collation.

Understand the failure class

Background: "already exists" / EEXIST / FileAlreadyExistsException: what the 'file already exists' error means and how to fix it — this error's family across 37 libraries.

Related errors

AI-assisted analysis of apache/dolphinscheduler@02eac45a1b (2026-09-06). Data as JSON: /api/errors/42b93f8da8e5228e. Report an issue: GitHub.