alibaba/spring-cloud-alibaba · critical · IOException

please set %s.appKey

Error message

please set %s.appKey

What it means

Thrown by JobSyncService.syncAppGroup(DefaultAcsClient) when SchedulerxProperties.appKey is null or empty. The appKey authenticates this application group against the Alibaba SchedulerX2 service; without it the CreateAppGroup POP call cannot be issued, so the method logs the error and aborts with an IOException. The message is built with String.format using CONFIG_PREFIX ('spring.cloud.scheduling.schedulerx'). Because blockAppStart defaults to true, this exception surfaces at application startup during the scheduled job-sync phase.

Source

Thrown at spring-cloud-alibaba-starters/spring-cloud-starter-alibaba-schedulerx/src/main/java/com/alibaba/cloud/scheduling/schedulerx/service/JobSyncService.java:180

	}

	/**
	 * sync app group.
	 *
	 * @param client pop client
	 * @return sync app group result
	 * @throws IOException     sync app group exception.
	 * @throws ClientException sync app group pop client exception.
	 */
	public boolean syncAppGroup(DefaultAcsClient client) throws IOException, ClientException {
		if (StringUtils.isEmpty(properties.getAppName())) {
			logger.error("please set {}.appName", SchedulerxProperties.CONFIG_PREFIX);
			throw new IOException(String.format("please set %s.appName", SchedulerxProperties.CONFIG_PREFIX));
		}

		if (StringUtils.isEmpty(properties.getAppKey())) {
			logger.error("please set {}.appKey", SchedulerxProperties.CONFIG_PREFIX);
			throw new IOException(String.format("please set %s.appKey", SchedulerxProperties.CONFIG_PREFIX));
		}

		if (StringUtils.isEmpty(properties.getGroupId())) {
			logger.error("please set {}.groupId", SchedulerxProperties.CONFIG_PREFIX);
			throw new IOException(String.format("please set %s.groupId", SchedulerxProperties.CONFIG_PREFIX));
		}

		CreateAppGroupRequest request = new CreateAppGroupRequest();
		request.setNamespace(properties.getNamespace());
		request.setNamespaceSource(getNamespaceSource());
		request.setAppName(properties.getAppName());
		request.setGroupId(properties.getGroupId());
		request.setAppKey(properties.getAppKey());
		if (StringUtils.isNotEmpty(properties.getAlarmChannel())) {
			MonitorConfig monitorConfig = new MonitorConfig();
			monitorConfig.setSendChannel(properties.getAlarmChannel());
			request.setMonitorConfigJson(JsonUtil.toJson(monitorConfig));
		}

View on GitHub (pinned to 115d590110)

Solutions

1. Set spring.cloud.scheduling.schedulerx.appKey in application.yml/properties to the SchedulerX2 app key from the Alibaba Cloud console.
2. If the value comes from an environment variable, verify the variable is exported in the runtime environment (e.g. via ${SCHEDULERX_APP_KEY} and confirm it resolves).
3. Check YAML indentation: appKey must be a direct child of the spring.cloud.scheduling.schedulerx node, not nested under jobs.
4. Confirm there is no typo in the property name (case-sensitive) and no profile-specific file overriding it to blank.

Example fix

# before
spring:
  cloud:
    scheduling:
      schedulerx:
        appName: my-app
        groupId: app-123

# after
spring:
  cloud:
    scheduling:
      schedulerx:
        appName: my-app
        appKey: a1b2c3d4e5f6*******
        groupId: app-123

// Fail fast before job sync runs: validate the three required app-group fields.
@Bean
ApplicationListener<ApplicationReadyEvent> schedulerxConfigGuard(SchedulerxProperties p) {
    return e -> {
        if (p.isEnabled() && !p.getJobs().isEmpty()) {
            Assert.hasText(p.getAppName(), "spring.cloud.scheduling.schedulerx.appName must be set");
            Assert.hasText(p.getAppKey(), "spring.cloud.scheduling.schedulerx.appKey must be set");
            Assert.hasText(p.getGroupId(), "spring.cloud.scheduling.schedulerx.groupId must be set");
        }
    };
}

When it happens

Trigger: Calling syncAppGroup(client) while properties.getAppKey() returns null or "". The check is StringUtils.isEmpty(properties.getAppKey()) at JobSyncService.java:179-180. Reached when the starter auto-configures task sync (SchedulerxConfigurations, enabled by default) and any jobs are declared under spring.cloud.scheduling.schedulerx.jobs.

Common situations: Developer adds the schedulerx starter and configures appName/groupId but forgets appKey; or appKey is read from an environment variable that is unset in the deployment env; or a YAML indentation error places appKey under the wrong key so Spring does not bind it.

Related errors

• please set %s.groupId
• cron and oneTime shouldn't set together
• create schedulerx job failed, jobName={}, message={}
• update schedulerx job failed, jobName={}, message={}
• '/' must be followed by an integer.

AI-assisted analysis of alibaba/spring-cloud-alibaba@115d590110 (2026-08-14). Data as JSON: /api/errors/dd60076e8a43225a. Report an issue: GitHub.