SonarScanner "You must define the following mandatory properties: sonar.projectKey" in CI

By Kaveh Alemi·Latchkey

The scanner needs a sonar.projectKey to know which project to attach the analysis to. It found none on the command line, in sonar-project.properties, or in the action inputs, so it stops before analyzing.

What this error means

The scanner exits immediately with "ERROR: You must define the following mandatory properties for 'Unknown': sonar.projectKey".

ERROR: You must define the following mandatory properties for 'Unknown': sonar.projectKey
ERROR: Re-run SonarScanner using the -X switch to enable full debug logging.

Common causes

No project key is set anywhere

Neither a sonar-project.properties file nor a -Dsonar.projectKey= argument nor an action input provides the key.

The properties file is not in the scan working directory

A sonar-project.properties exists but the scanner runs from a different directory and never reads it.

How to fix it

Provide the project key explicitly

1. Get the project key from the project in SonarQube or SonarCloud.
2. Set it in sonar-project.properties at the scan root, or pass it as an argument.
3. Re-run so the scanner attaches the analysis to the right project.

sonar.projectKey=my-org_my-repo
sonar.organization=my-org

Pass the key through the action inputs

When using a scan action, set the arguments so the key is present even without a properties file.

- uses: SonarSource/sonarqube-scan-action@v4
  with:
    args: >
      -Dsonar.projectKey=my-org_my-repo

How to prevent it

• Commit sonar-project.properties with the project key at the repo root.
• Run the scanner from the directory that holds the properties file.
• Keep the key identical to the one shown in the project settings.

Frequently asked questions

Related guides

References

• GitHub Actions documentation