apache/shenyu · critical · ShenyuException

sync.consul.url can not be null.

Error message

sync.consul.url can not be null.

What it means

ConsulSyncConfiguration.consulClient builds the ConsulClient bean from sync.consul.url in ConsulProperties. If the URL property is blank, the configuration cannot know where Consul lives, so a ShenyuException is thrown at bean creation time, failing application startup.

Solutions

1. Set sync.consul.url (e.g. http://localhost:8500) in application.yml for the active profile.
2. Confirm the ConsulProperties prefix/binding matches the key you set (check the @ConfigurationProperties prefix).
3. Disable the consul listener module if you do not use Consul sync.
4. Provide the value via environment variable (e.g. SYNC_CONSUL_URL) in containerized deployments.

Example fix

# before (application.yml)
consul:
  url:
# after
consul:
  url: http://localhost:8500

String url = properties.getUrl();
if (url == null || url.isBlank()) { throw new IllegalStateException("sync.consul.url must be set before enabling consul sync"); }

boolean consulUrlPresent(Map<String,String> cfg) { String u = cfg.get("sync.consul.url"); return u != null && !u.isBlank(); }

try { new ConsulSyncConfiguration().consulClient(props); } catch (ShenyuException e) { log.error("Consul URL missing: {}", e.getMessage()); /* fail startup or fall back */ }

When it happens

Trigger: Starting shenyu-admin with the consul data-sync listener enabled but shenyu.consul.url (sync.consul.url) unset or empty in application.yml/properties.

Common situations: Enabling the consul sync dependency without adding its configuration block, copying a config template and leaving the URL placeholder empty, or an environment-specific profile that omits the property.

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

• sync.consul.url formatter is not incorrect.
• apollo client getItemValue time out
• e.getMessage()
• e.getMessage()
• e.getMessage()

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

Appendix: source

Thrown at shenyu-admin-listener/shenyu-admin-listener-consul/src/main/java/org/apache/shenyu/admin/config/ConsulSyncConfiguration.java:55

/**
 * The type Consul listener.
 */
@Configuration
@ConditionalOnProperty(prefix = "shenyu.sync.consul", name = "url")
@EnableConfigurationProperties(ConsulProperties.class)
public class ConsulSyncConfiguration {

    /**
     * init Consul client.
     *
     * @param consulProperties the consul properties
     * @return Consul client
     */
    @Bean
    public ConsulClient consulClient(final ConsulProperties consulProperties) {
        String url = consulProperties.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.");
        }
    }

    /**
     * Config event listener data changed listener.
     *
     * @param consulClient the consul client
     * @return the data changed listener
     */
    @Bean
    @ConditionalOnMissingBean(ConsulDataChangedListener.class)
    public DataChangedListener consulDataChangedListener(final ConsulClient consulClient) {

View on GitHub (pinned to 567142e072)