SonarSource/sonarqube · error · IllegalArgumentException

Failed to unset the New Code Definition. Your

Error message

Failed to unset the New Code Definition. Your %s New Code Definition is not compatible with the Clean as You Code methodology. Please update your %s New Code Definition

What it means

When unsetting a project/branch New Code Definition, UnsetAction falls back to the instance-level definition. checkInstanceNcdCompliant verifies that global NCD is compatible with Clean as You Code (via CaycUtils.isNewCodePeriodCompliant); if it is not, the unset is refused because the project would inherit a non-compliant definition.

Solutions

  1. Update the instance-level New Code Definition (api/new_code_periods/set without project key) to a CaYC-compliant type/value, e.g. DAYS with value <= 30 (e.g. previous_version or 30 days)
  2. Set a CaYC-compliant definition directly on the project instead of relying on inheritance, then retry the unset
  3. Choose a compliant reference branch strategy (PREVIOUS_VERSION) as the global setting

Example fix

// before: unset fails because global NCD = DAYS 365
POST /api/new_code_periods/unset?project=my_project

// after: fix global definition first
POST /api/new_code_periods/set?value=30&type=DAYS
POST /api/new_code_periods/unset?project=my_project
Defensive patterns

Strategy: try-catch

Validate before calling

// check global NCD compliance before unsetting a project/branch
defaults = await get('/api/new_code_periods/show');
compliant = ['PREVIOUS_VERSION'].includes(defaults.type) || (defaults.type === 'DAYS' && Number(defaults.value) <= 30);

Type guard

function isCaYCCompliant(ncd) { return ncd.type === 'PREVIOUS_VERSION' || (ncd.type === 'DAYS' && Number(ncd.value) <= 30); }

Try / catch

try { await api.unsetNcd({ project }); } catch (e) { if (e.message.includes('Clean as You Code')) { await setInstanceNcd({ type: 'DAYS', value: '30' }); await api.unsetNcd({ project }); } else { throw e; } }

Prevention

When it happens

Trigger: POST api/new_code_periods/unset where the project/branch has no own NCD, no inherited parent NCD, and the instance-level NCD (from api/new_code_periods/set at global level) uses a non-CaYC-compliant type/value such as a specific number of days like 365.

Common situations: Instance upgraded to a SonarQube version enforcing CaYC while the global New Code Period was set to an old non-compliant value (e.g. 30/90 days is fine but 365 is not); admin tries to reset a project to inherit the global setting which is invalid.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

AI-assisted analysis of SonarSource/sonarqube@184c821202 (2026-09-09). Data as JSON: /api/errors/527ef6cbb074c143. Report an issue: GitHub.

Appendix: source

Thrown at server/sonar-webserver-webapi/src/main/java/org/sonar/server/newcodeperiod/ws/UnsetAction.java:160

      .findFirst()
      .orElseThrow(() -> new NotFoundException(format("Main branch in project '%s' not found", project.getKey())));
  }

  private BranchDto getBranch(DbSession dbSession, ProjectDto project, String branchKey) {
    return dbClient.branchDao().selectByBranchKey(dbSession, project.getUuid(), branchKey)
      .orElseThrow(() -> new NotFoundException(format("Branch '%s' in project '%s' not found", branchKey, project.getKey())));
  }

  private ProjectDto getProject(DbSession dbSession, String projectKey) {
    return componentFinder.getProjectByKey(dbSession, projectKey);
  }

  private void checkInstanceNcdCompliant(DbSession dbSession) {
    var instanceNcd = newCodePeriodDao.selectGlobal(dbSession);
    if (instanceNcd.isPresent()) {
      var ncd = instanceNcd.get();
      if (!CaycUtils.isNewCodePeriodCompliant(ncd.getType(), ncd.getValue())) {
        throw new IllegalArgumentException(format(NON_COMPLIANT_CAYC_ERROR_MESSAGE, INSTANCE, INSTANCE));
      }
    }
  }

  private void checkBranchInheritedNcdCompliant(DbSession dbSession, String projectUuid) {
    var projectNcd = newCodePeriodDao.selectByProject(dbSession, projectUuid);
    if (projectNcd.isPresent()) {
      var ncd = projectNcd.get();
      if (!CaycUtils.isNewCodePeriodCompliant(ncd.getType(), ncd.getValue())) {
        throw new IllegalArgumentException(format(NON_COMPLIANT_CAYC_ERROR_MESSAGE, PROJECT, PROJECT));
      }
    } else {
      checkInstanceNcdCompliant(dbSession);
    }
  }

}

View on GitHub (pinned to 184c821202)