What causes "namespaceId is not exist" in apache/shenyu?

Create the namespace in the admin dashboard (System -> Namespace) before clients register

apache/shenyu · error · IllegalArgumentException

namespaceId is not exist

Error message

namespaceId is not exist

What it means

ShenyuClientHttpRegistryController.checkClientNamespaceExist validates, before any client registration operation, that the supplied namespaceId resolves to a namespace via namespaceService.findByNamespaceId. If none is found it throws IllegalArgumentException("namespaceId is not exist"), rejecting the registration call.

Solutions

Create the namespace in the admin dashboard (System -> Namespace) before clients register
Align the client's shenyu.register.namespace property with a registered admin namespace id
Re-seed the admin DB's namespace table if it was wiped during migration

Example fix

// before (client config)
shenyu:
  register:
    namespace: my-ns        // not registered in admin
// after
shenyu:
  register:
    namespace: 649330b6-c2d7-4f6c-9b2c-9f5c7f1b2f3a   // registered

Defensive patterns

Strategy: validation

Validate before calling

// on the client, before registering
if (!namespaceRegisteredInAdmin(namespaceId)) {
    throw new IllegalStateException("namespaceId is not registered in admin: " + namespaceId);
}

Try / catch

try {
    registryClient.register(metadata);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("namespaceId is not exist")) { /* create namespace or fix client config */ }
}

Prevention

Create namespaces in admin before starting any Shenyu clients
Keep shenyu.register.namespace identical across client configs per environment
After DB re-initialization, recreate namespaces before clients reconnect

When it happens

Trigger: A Shenyu client (spring-mvc/dubbo etc.) registers over HTTP with a namespaceId that admin has not registered; typical path is any register/registerUri/registerMetadata endpoint that invokes this check.

Common situations: Client's shenyu.register.namespace config not matching an admin namespace; admin DB reinitialized losing namespaces; multi-environment setup with mismatched ids.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

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

Appendix: source

Thrown at shenyu-admin/src/main/java/org/apache/shenyu/admin/controller/ShenyuClientHttpRegistryController.java:149

     * Offline result string.
     *
     * @param offlineDTO the offline dto
     * @return the string
     */
    @PostMapping("/offline")
    @ResponseBody
    public String offline(@RequestBody final URIRegisterDTO offlineDTO) {
        if (Objects.isNull(offlineDTO.getNamespaceId())) {
            offlineDTO.setNamespaceId(Constants.SYS_DEFAULT_NAMESPACE_ID);
        }
        publisher.publish(offlineDTO);
        return ShenyuResultMessage.SUCCESS;
    }

    public void checkClientNamespaceExist(final String namespaceId) {
        NamespaceVO namespaceVO = namespaceService.findByNamespaceId(namespaceId);
        if (Objects.isNull(namespaceVO)) {
            throw new IllegalArgumentException("namespaceId is not exist");
        }
    }
}

View on GitHub (pinned to 567142e072)