What causes "Please provide the Personal Access Token to update the URL." in SonarSource/sonarqube?

Include the current or new PAT when changing the URL

SonarSource/sonarqube · error · IllegalArgumentException

Please provide the Personal Access Token to update the URL.

Error message

Please provide the Personal Access Token to update the URL.

What it means

IllegalArgumentException from AlmSettingsSupport.checkCredentialArtifactOnUrlUpdate (reached via checkPatOnUrlUpdate): when updating an ALM setting, the URL is being changed but no new Personal Access Token was supplied. The server requires the credential to re-validate the new endpoint, since the old PAT may not work against a different URL.

Source

Thrown at server/sonar-webserver-webapi/src/main/java/org/sonar/server/almsettings/ws/AlmSettingsSupport.java:261

      .setWebhookSecret(setting.webhookSecret()));
  }

  public AlmSettingDto getAlmSetting(DbSession dbSession, String almSetting) {
    return dbClient.almSettingDao().selectByKey(dbSession, almSetting)
      .orElseThrow(() -> new NotFoundException(format("DevOps Platform setting with key '%s' cannot be found", almSetting)));
  }

  public void checkPrivateKeyOnUrlUpdate(AlmSettingDto almSettingDto, String url, @Nullable String privateKey) {
    checkCredentialArtifactOnUrlUpdate(url, almSettingDto, privateKey, "Please provide the Private Key to update the URL.");
  }

  public void checkPatOnUrlUpdate(AlmSettingDto almSettingDto, String url, @Nullable String pat) {
    checkCredentialArtifactOnUrlUpdate(url, almSettingDto, pat, "Please provide the Personal Access Token to update the URL.");
  }

  private static void checkCredentialArtifactOnUrlUpdate(String url, AlmSettingDto almSettingDto, @Nullable String credentialArtifact, String errorMessage) {
    if (!url.equals(almSettingDto.getUrl()) && isEmpty(credentialArtifact)) {
      throw new IllegalArgumentException(errorMessage);
    }
  }
}

View on GitHub (pinned to 184c821202)

Solutions

Include the current or new PAT when changing the URL
If only the PAT changes, keep the URL unchanged
Temporarily delete and re-create the setting with the new URL and PAT if the old credential is unknown

Example fix

// before
POST /api/alm_settings/update_azure key=azure url=https://new-url (no pat)
// after
POST /api/alm_settings/update_azure key=azure url=https://new-url pat=<token>

Defensive patterns

Strategy: validation

Validate before calling

const current = await ws.get('api/alm_settings/list');
const s = current.almSettings.find(x => x.key === key);
if (s && url !== s.url && !pat) {
  throw new Error('Changing the URL requires re-supplying the PAT');
}

Type guard

const urlChanged = (s, newUrl) => s?.url !== newUrl;

Try / catch

try {
  await ws.post('api/alm_settings/update_azure', {key, url, pat});
} catch (e) {
  if (e.status === 400 && /Please provide the Personal Access Token/.test(e.message)) {
    const pat = await promptForPat();
    await ws.post('api/alm_settings/update_azure', {key, url, pat});
  } else { throw e; }
}

Prevention

Always send pat (even unchanged) whenever url changes in automation
Never patch URL-only in integration updates
Store the PAT in a secret manager so rotation scripts can supply it

When it happens

Trigger: POST api/alm_settings/update_azure (or similar) where url differs from the stored url and pat is empty/null.

Common situations: Rotating the server URL of an Azure DevOps organization without re-entering the PAT; automation that only patches the URL field.

Related errors

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