alibaba/nacos · error · IllegalArgumentException

Runtime Endpoint bindings must not be empty

Error message

Runtime Endpoint bindings must not be empty

What it means

Thrown by validateRuntimeEndpointSnapshotItem when a RuntimeEndpointSnapshotItem.getBindings() is a non-null but empty list. Every runtime endpoint must declare at least one RuntimeVersionBinding tying the endpoint's address to the Agent version range it can serve; an endpoint with no version binding is meaningless to the discovery layer, so the validator treats emptiness as invalid (a null bindings list would have already failed the requireNonNull check with a different message).

Source

Thrown at api/src/main/java/com/alibaba/nacos/api/ai/utils/AgentModelValidator.java:565

            }
        }
    }
    
    private static void validateRuntimeEndpointSnapshotItem(RuntimeEndpointSnapshot snapshot,
        AgentVersion selectedVersion, RuntimeEndpointSnapshotItem item,
        Set<EndpointNaturalKey> endpointKeys) {
        requireNonNull(item, "runtimeEndpointSnapshot item");
        validateEndpoint(item.getEndpoint());
        EndpointNaturalKey endpointKey = EndpointNaturalKey.of(snapshot.getNamespaceId(),
            snapshot.getAgentName(), snapshot.getProtocol(), item.getEndpoint());
        if (!endpointKeys.add(endpointKey)) {
            throw new IllegalArgumentException("Duplicate runtime Endpoint: " + endpointKey);
        }
        
        List<RuntimeVersionBinding> bindings = item.getBindings();
        requireNonNull(bindings, "runtimeEndpointSnapshot.bindings");
        if (bindings.isEmpty()) {
            throw new IllegalArgumentException("Runtime Endpoint bindings must not be empty");
        }
        Set<String> bindingKeys = new HashSet<String>();
        for (RuntimeVersionBinding binding : bindings) {
            validateRuntimeVersionBinding(binding, selectedVersion, bindingKeys);
        }
        requireNonNull(item.getState(), "runtime Endpoint state");
        requireNonNull(item.getEnabled(), "runtime Endpoint enabled");
        requireNonNull(item.getHealthy(), "runtime Endpoint healthy");
        validateRuntimeEndpointState(item);
        validateEpochMillis(item.getLastUpdatedTime(), "lastUpdatedTime");
    }
    
    private static void validateRuntimeVersionBinding(RuntimeVersionBinding binding,
        AgentVersion selectedVersion, Set<String> bindingKeys) {
        requireNonNull(binding, "runtime Version binding");
        AgentVersion runtimeVersion = AgentVersion.parse(binding.getRuntimeVersion());
        AgentVersionRange versionRange = AgentVersionRange.parse(binding.getVersionRange());
        if (!versionRange.getValue().equals(binding.getVersionRange())) {

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Populate item.bindings with at least one RuntimeVersionBinding whose runtimeVersion and versionRange are valid and consistent.
2. If the endpoint genuinely has no version to serve, remove the whole RuntimeEndpointSnapshotItem from snapshot.items instead of leaving it bindingless.
3. Ensure your snapshot builder does not emit items whose binding list was emptied by an upstream filter.

Example fix

// before
item.setBindings(Collections.emptyList()); // rejected
// after
RuntimeVersionBinding b = new RuntimeVersionBinding();
b.setRuntimeVersion("1.0.0");
b.setVersionRange("[1.0.0,2.0.0)");
item.setBindings(List.of(b));

for (RuntimeEndpointSnapshotItem it : snapshot.getItems()) {
    List<RuntimeVersionBinding> b = it.getBindings();
    if (b == null || b.isEmpty()) {
        throw new IllegalStateException("item has no bindings: " + it.getEndpoint());
    }
}

static boolean everyItemHasBindings(List<RuntimeEndpointSnapshotItem> items) {
    for (RuntimeEndpointSnapshotItem it : items) {
        List<RuntimeVersionBinding> b = it.getBindings();
        if (b == null || b.isEmpty()) return false;
    }
    return true;
}

try {
    AgentModelValidator.validateRuntimeEndpointSnapshot(snapshot);
} catch (IllegalArgumentException e) {
    if (e.getMessage().equals("Runtime Endpoint bindings must not be empty")) {
        // remove the item or add a valid binding
    } else throw e;
}

When it happens

Trigger: Pushing a RuntimeEndpointSnapshot whose item.bindings is [] (present but empty). Reached through AgentModelValidator.validateRuntimeEndpointSnapshot in the runtime management/RAD push flow.

Common situations: Serializing an item from a struct whose bindings were filtered out (e.g. all bindings removed because their version range was invalid) leaving an empty list instead of omitting the field; a builder that initializes bindings = new ArrayList<>() and never adds to it; a partial-update payload that zeroes the bindings array.

Related errors

• versionRange must contain runtimeVersion: {runtimeVersion}
• Snapshot binding does not match selected Version: {selectedV
• Duplicate Runtime Version binding
• Duplicate runtime Endpoint: {endpointKey}
• Runtime Version range must be canonical

AI-assisted analysis of alibaba/nacos@9b989acdf1 (2026-08-14). Data as JSON: /api/errors/00bc30d06c07b8fd. Report an issue: GitHub.