SonarSource/sonarqube · error · IllegalStateException

Failed to create the GitHub App from manifest. GitHub return

Error message

Failed to create the GitHub App from manifest. GitHub returned code 

What it means

convertAppManifest converts a GitHub App manifest code into App credentials after a manifest-based App creation. If GitHub returns a status other than 201 or 200, the body is logged at DEBUG and this IllegalStateException is thrown with the returned code. It means the manifest conversion endpoint rejected the request.

Source

Thrown at server/sonar-alm-client/src/main/java/org/sonar/alm/client/github/GithubApplicationClientImpl.java:418

      LOG.error("Failed to create GitHub's user access token. GitHub's response: {}", content);
      throw new IllegalArgumentException();
    } catch (IOException e) {
      throw new IllegalStateException("Failed to create GitHub's user access token", e);
    }
  }

  @Override
  public GithubAppCredentials convertAppManifest(String apiEndpoint, String code) {
    String endpoint = "/app-manifests/" + URLEncoder.encode(code, StandardCharsets.UTF_8) + "/conversions";
    try {
      // Unauthenticated call: the GitHub App does not exist yet, so no JWT/app token is available.
      ApplicationHttpClient.Response response = githubApplicationHttpClient.post(apiEndpoint, null, endpoint);

      if (response.getCode() != HTTP_CREATED && response.getCode() != HTTP_OK) {
        if (LOG.isDebugEnabled()) {
          LOG.debug("GitHub manifest conversion failed, response body: {}", response.getContent().orElse(""));
        }
        throw new IllegalStateException(
          "Failed to create the GitHub App from manifest. GitHub returned code " + response.getCode());
      }

      return response.getContent()
        .map(content -> GSON.fromJson(content, GithubAppCredentials.class))
        .orElseThrow(() -> new IllegalStateException("Failed to create the GitHub App from manifest, response body was empty"));
    } catch (IOException e) {
      throw new IllegalStateException("Failed to create the GitHub App from manifest", e);
    }
  }

  @Override
  public GithubBinding.GsonApp getApp(GithubAppConfiguration githubAppConfiguration) {
    AppToken appToken = appSecurity.createAppToken(githubAppConfiguration.getId(), githubAppConfiguration.getPrivateKey());
    String endpoint = "/app";
    return getOrThrowIfNotHttpOk(githubAppConfiguration.getApiEndpoint(), appToken, endpoint, GithubBinding.GsonApp.class);
  }

View on GitHub (pinned to 184c821202)

Solutions

1. Restart the App creation flow from the beginning to get a fresh manifest code and convert it promptly.
2. Verify the apiEndpoint matches your GitHub instance (https://api.github.com or GHES host).
3. Enable DEBUG logging to inspect the error response body from GitHub.
4. Check GitHub status for outages if a 5xx code is reported and retry.

Example fix

// before
client.convertAppManifest(endpoint, oldCode); // code already used/expired
// after
String freshCode = redoAppManifestFlow(); client.convertAppManifest(endpoint, freshCode);

// use the code immediately after obtaining it
if (code == null || code.isBlank()) throw new IllegalArgumentException("Manifest code required");
Instant obtainedAt = Instant.now(); if (Duration.between(obtainedAt, Instant.now()).toMinutes() > 8) throw new IllegalStateException("Manifest code likely expired; restart flow");

try { client.convertAppManifest(endpoint, code); } catch (IllegalStateException e) { if (e.getMessage().contains("returned code 5")) retryWithBackoff(3, e); else throw e; }

When it happens

Trigger: Calling convertAppManifest(apiEndpoint, code) when the POST response code is not 201/200 — expired or already-used manifest code, wrong apiEndpoint, or GitHub server error.

Common situations: User delayed between creating the App from manifest and SonarQube converting it (code expires in ~10 minutes), the conversion was already completed once (codes are single-use), incorrect GHES API endpoint configured.

Understand the failure class

Background: "API error: {status}" and "HTTP 401/403/404/429/5xx" errors: non-2xx HTTP responses explained — this error's family across 27 libraries.

Related errors

• Failed to check permissions with Github, check the configura
• Failed to list all repositories of '%s' accessible by user a
• Failed to get repository '%s' on '%s' (this might be related
• Failed to create GitHub's user access token. GitHub returned
• Failed to list all organizations accessible by user access t

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