What causes "sync.consul.url can not be null." in apache/shenyu?

apache/shenyu · error · ShenyuException

sync.consul.url can not be null.

Error message

sync.consul.url can not be null.

What it means

The Consul data-sync configuration requires the Consul agent URL. If shenyu.sync.consul.url is blank, the consulClient bean throws this ShenyuException; a non-blank but malformed URL throws the companion 'formatter is not incorrect' error.

Solutions

Set shenyu.sync.consul.url (e.g. http://127.0.0.1:8500)
Ensure the key is under shenyu.sync.consul, not another prefix
Check that the property source (yml/env) supplying the URL is actually active

Example fix

# before
shenyu:
  sync:
    consul: {}
# after
shenyu:
  sync:
    consul:
      url: http://127.0.0.1:8500

Defensive patterns

Strategy: validation

Validate before calling

String url = env.getProperty("shenyu.sync.consul.url");
if (StringUtils.isBlank(url)) {
    throw new IllegalArgumentException("shenyu.sync.consul.url is required for consul data sync");
}
new URL(url); // also fail fast on malformed values

Try / catch

try {
    consulClient = ctx.getBean(ConsulClient.class);
} catch (Exception e) {
    if (rootCauseOf(e, ShenyuException.class).map(x -> x.getMessage().contains("sync.consul.url")).orElse(false)) {
        log.error("Set shenyu.sync.consul.url, e.g. http://127.0.0.1:8500");
    } else throw e;
}

Prevention

Keep sync config under the shenyu.sync.consul prefix, not spring.cloud.consul
Validate the URL scheme/host/port in config tests
Check env substitution resolves to a non-empty value in every environment

When it happens

Trigger: Using the consul data-sync starter without setting shenyu.sync.consul.url, or setting it to an empty/whitespace string.

Common situations: Switching sync type to consul without adding the url key; env var substitution resolving to empty; config placed under the wrong prefix (e.g. spring.cloud.consul instead of shenyu.sync.consul).

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

AI-assisted analysis of apache/shenyu@567142e072 (2026-09-12). Data as JSON: /api/errors/fe5d4a2104da04b8. Report an issue: GitHub.

Appendix: source

Thrown at shenyu-spring-boot-starter/shenyu-spring-boot-starter-sync-data-center/shenyu-spring-boot-starter-sync-data-consul/src/main/java/org/apache/shenyu/springboot/sync/data/consul/ConsulSyncDataConfiguration.java:105

     * @return the consul config
     */
    @Bean
    @ConfigurationProperties(prefix = "shenyu.sync.consul")
    public ConsulConfig consulConfig() {
        return new ConsulConfig();
    }


    /**
     * init Consul client.
     * @param consulConfig the consul config
     * @return Consul client
     */
    @Bean
    public ConsulClient consulClient(final ConsulConfig consulConfig) {
        String url = consulConfig.getUrl();
        if (StringUtils.isBlank(url)) {
            throw new ShenyuException("sync.consul.url can not be null.");
        }
        try {
            URL consulUrl = new URL(url);
            return consulUrl.getPort() < 0 ? new ConsulClient(consulUrl.getHost()) : new ConsulClient(consulUrl.getHost(), consulUrl.getPort());
        } catch (MalformedURLException e) {
            throw new ShenyuException("sync.consul.url formatter is not incorrect.");
        }
    }
}

View on GitHub (pinned to 567142e072)