What causes "Invalid AppId format: %s" in apolloconfig/apollo?

Use only digits, letters, hyphens, underscores, and dots in the appId, ensuring it does not start with a dot.

apolloconfig/apollo · error · BadRequestException

Invalid AppId format: %s

Error message

Invalid AppId format: %s

What it means

Thrown by AppController.validatePortalApp when the auth type is USER and the appId does not match the InputValidator.CLUSTER_NAMESPACE_VALIDATOR pattern: [0-9a-zA-Z_-]+[0-9a-zA-Z_.-]*. This means the appId must start with a digit, letter, hyphen, or underscore, and subsequent characters can also include dots (but not a single dot alone). The error message includes the constant INVALID_CLUSTER_NAMESPACE_MESSAGE. Results in HTTP 400.

Source

Thrown at apollo-portal/src/main/java/com/ctrip/framework/apollo/openapi/v1/controller/AppController.java:296

      }
      if (userService.findByUserId(operator) == null) {
        throw BadRequestException.userNotExists(operator);
      }
      return operator;
    }

    throw new BadRequestException("Unsupported auth type: %s", authType);
  }

  private void validatePortalApp(OpenAppDTO app) {
    if (!UserIdentityConstants.USER.equals(UserIdentityContextHolder.getAuthType())) {
      return;
    }
    if (!StringUtils.hasText(app.getName())) {
      throw BadRequestException.appNameIsBlank();
    }
    if (!InputValidator.isValidClusterNamespace(app.getAppId())) {
      throw new BadRequestException("Invalid AppId format: %s",
          InputValidator.INVALID_CLUSTER_NAMESPACE_MESSAGE);
    }
    if (!StringUtils.hasText(app.getOrgId())) {
      throw BadRequestException.orgIdIsBlank();
    }
    if (!StringUtils.hasText(app.getOrgName())) {
      throw new BadRequestException("orgName can not be blank");
    }
    if (!StringUtils.hasText(app.getOwnerName())) {
      throw BadRequestException.ownerNameIsBlank();
    }
  }

  private Set<String> findAppIdsAuthorizedByCurrentIdentity() {
    if (UserIdentityConstants.USER.equals(UserIdentityContextHolder.getAuthType())) {
      UserInfo loginUser = userInfoHolder.getUser();
      if (loginUser == null || !StringUtils.hasText(loginUser.getUserId())) {
        return Collections.emptySet();

View on GitHub (pinned to d95fc18d11)

Solutions

Use only digits, letters, hyphens, underscores, and dots in the appId, ensuring it does not start with a dot.
Sanitize the appId input on the client side before submission.
Follow Apollo's naming convention: a short alphanumeric identifier like 'my-app' or 'payment-service'.

Example fix

// before
app.setAppId("my app@v2");

// after
app.setAppId("my-app-v2");

Defensive patterns

Strategy: validation

Validate before calling

// Validate appId format before creating/updating an app (USER auth)
if (!InputValidator.isValidClusterNamespace(app.getAppId())) {
    throw new IllegalArgumentException(
        "Invalid AppId format: " + InputValidator.INVALID_CLUSTER_NAMESPACE_MESSAGE);
}

Type guard

public static boolean hasValidAppIdFormat(String appId) {
    return InputValidator.isValidClusterNamespace(appId);
}

Prevention

Run InputValidator.isValidClusterNamespace on the appId client-side before submission.
Use a naming convention that only uses letters, digits, hyphens, and underscores.
Sanitize user input by stripping whitespace and rejecting special characters early.

When it happens

Trigger: Creating or updating an app (createApp, updateApp, createAppInEnv) with a USER identity where app.getAppId() contains spaces, special characters like @, #, /, or starts with a dot. For non-USER auth types, this validation is skipped entirely.

Common situations: A user enters an appId with spaces or special characters in the Portal UI. An appId starts with a dot (e.g., '.myapp'). A copy-paste introduced invisible characters. The appId contains a slash (common when people try to use a path-like identifier).

Related errors

AI-assisted analysis of apolloconfig/apollo@d95fc18d11 (2026-08-14). Data as JSON: /api/errors/3d6c40f1624b7bd0. Report an issue: GitHub.