What causes "PROJECT_NOT_EXIST" in apache/dolphinscheduler?

Verify the project code/name exists (query the t_ds_project table or GET /projects list) before the call

apache/dolphinscheduler · error · ServiceException

PROJECT_NOT_EXIST

PROJECT_NOT_EXIST

Error message

PROJECT_NOT_EXIST

What it means

Thrown by ProjectServiceImpl.checkProjectAndAuthThrowException when the Project lookup yields null, i.e. the requested project does not exist in the database. It is the project-existence gate used by queryByCode, queryByName, deleteProject and queryAuthorizedUser before any authorization check.

Source

Thrown at dolphinscheduler-api/src/main/java/org/apache/dolphinscheduler/api/service/impl/ProjectServiceImpl.java:185

        Project project = projectDao.queryByCode(projectCode);
        checkProjectAndAuthThrowException(loginUser, project, PROJECT);
        result.setData(project);
        putMsg(result, Status.SUCCESS);
        return result;
    }

    @Override
    public Project queryByName(User loginUser, String projectName) {
        Project project = projectDao.queryByName(projectName);
        checkProjectAndAuthThrowException(loginUser, project, PROJECT);
        return project;
    }

    @Override
    public void checkProjectAndAuthThrowException(@NonNull User loginUser, @Nullable Project project,
                                                  String permission) {
        if (project == null) {
            throw new ServiceException(Status.PROJECT_NOT_EXIST);
        }
        if (!canOperatorPermissions(loginUser, new Object[]{project.getId()}, AuthorizationType.PROJECTS, permission)) {
            throw new ServiceException(Status.USER_NO_OPERATION_PROJECT_PERM, loginUser.getUserName(),
                    project.getCode());
        }
    }

    @Override
    public void checkProjectAndAuthThrowException(User loginUser, Long projectCode, String permission) {
        if (projectCode == null) {
            throw new ServiceException(Status.PROJECT_NOT_EXIST);
        }
        Project project = projectDao.queryByCode(projectCode);
        checkProjectAndAuthThrowException(loginUser, project, permission);
    }

    @Override
    public void checkHasProjectWritePermissionThrowException(User loginUser, long projectCode) {

View on GitHub (pinned to 02eac45a1b)

Solutions

Verify the project code/name exists (query the t_ds_project table or GET /projects list) before the call
Check the caller is not passing null projectCode; reject null/blank at the controller
Re-fetch the project code from the server rather than using a cached value

Example fix

// before
projectService.checkProjectAndAuthThrowException(loginUser, projectCode, Permissions.READ);
// after
Project project = projectDao.queryByCode(projectCode);
if (project == null) {
    putMsg(result, Status.PROJECT_NOT_EXIST);
    return result;
}
projectService.checkProjectAndAuthThrowException(loginUser, project, Permissions.READ);

Defensive patterns

Strategy: validation

Validate before calling

Project project = projectDao.queryByCode(projectCode);
if (project == null) { throw new ProjectNotFoundException(projectCode); }

Type guard

if (projectCode == null) return false;
return projectDao.queryByCode(projectCode) != null;

Try / catch

try {
    service.checkProjectAndAuthThrowException(loginUser, projectCode, perm);
} catch (ServiceException e) {
    if (e.getCode() == Status.PROJECT_NOT_EXIST) { /* render 'project not found' UI */ }
    throw e;
}

Prevention

Resolve project codes from the server list API instead of hardcoding
Null-check projectCode before service calls
Refresh cached project references after deletions

When it happens

Trigger: Calling queryByCode/queryByName with a code/name that matches no project; calling the Long projectCode overload with projectCode=null; the project was deleted between obtaining the code and the call.

Common situations: Stale project codes cached in clients after a project was dropped; typos in project names; passing null projectCode from an unvalidated request parameter; multi-env setups pointing at the wrong database.

Understand the failure class

Background: "Not found" and "does not exist" errors: why "Task not found", "No such folder", and "Can't find" fire when a lookup comes back empty — this error's family across 14 libraries.

Related errors

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