SonarSource/sonarqube · error · IllegalArgumentException

Unknown type '%s'

Error message

Unknown type '%s'

What it means

SetHomepageAction throws this IllegalArgumentException when the requested homepage 'type' parameter is a known enum value whose rendering still requires a component uuid that is absent, or falls through to an unhandled enum constant. It signals the server received a homepage type it cannot resolve to a configuration — either the type is genuinely unknown to this SonarQube version or a required companion parameter (component) was omitted/blank.

Source

Thrown at server/sonar-webserver-webapi/src/main/java/org/sonar/server/user/ws/SetHomepageAction.java:126

    }

    response.noContent();
  }

  @CheckForNull
  private String getHomepageParameter(DbSession dbSession, HomepageTypes.Type type, @Nullable String componentParameter, @Nullable String branchParameter) {
    switch (type) {
      case PROJECT:
        checkArgument(isNotBlank(componentParameter), PARAMETER_REQUIRED, type.name(), PARAM_COMPONENT);
        ProjectDto projectDto = componentFinder.getProjectByKey(dbSession, componentParameter);
        return componentFinder.getBranchOrPullRequest(dbSession, projectDto, branchParameter, null).getUuid();
      case PORTFOLIO, APPLICATION:
        checkArgument(isNotBlank(componentParameter), PARAMETER_REQUIRED, type.name(), PARAM_COMPONENT);
        return componentFinder.getByKey(dbSession, componentParameter).uuid();
      case PORTFOLIOS, PROJECTS, ISSUES:
        return null;
      default:
        throw new IllegalArgumentException(format("Unknown type '%s'", type.name()));
    }
  }

}

View on GitHub (pinned to 184c821202)

Solutions

1. When type is PORTFOLIO or APPLICATION, always pass component=<key> of the portfolio/application.
2. Align client and server versions — the homepage type may only exist in a different SonarQube/LTS version; upgrade the server or pin the UI plugin.
3. Use a supported type (PROJECTS, PORTFOLIOS, ISSUES) which require no component parameter.
4. Check the exact spelling/casing of the type value against the server's supported enum via the web UI settings page.

Example fix

// before: portfolio homepage without component
curl -u "$TOKEN:" -X POST 'https://sonar/api/users/set_homepage?type=PORTFOLIO'
// after: include the component key
curl -u "$TOKEN:" -X POST 'https://sonar/api/users/set_homepage?type=PORTFOLIO&component=my-portfolio-key'

const needsComponent = ['PORTFOLIO','APPLICATION'].includes(type);
if (needsComponent && !component) throw new Error(`homepage type ${type} requires a component parameter`);
const supported = ['PROJECTS','PORTFOLIOS','ISSUES','PORTFOLIO','APPLICATION'];
if (!supported.includes(type)) throw new Error(`homepage type ${type} unknown on this server version`);

function isKnownHomepageType(t) {
  return ['PROJECTS','PORTFOLIOS','ISSUES','PORTFOLIO','APPLICATION'].includes(t);
}

try {
  await setHomepage(type, component);
} catch (e) {
  if (e.status === 400 && /Unknown type/.test(e.message)) {
    await setHomepage('PROJECTS'); // fall back to a safe default homepage
  } else throw e;
}

When it happens

Trigger: POST api/users/set_homepage with type set to PORTFOLIO or APPLICATION but no/blank 'component' parameter, or a type value not present in the server's HomepageType enum.

Common situations: Newer client UI sends a homepage type unknown to an older/newer server after upgrade/downgrade mismatch; scripted API call omits component for portfolio/application homepages; hand-crafted type string casing mismatch.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Invalid value for property %s: [%s], only [%s] are allowed
• Unsupported WorkersPauseStatus: ${status}
• Invalid message type:
• Unexpected message type:
• Invalid type: %s

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