What causes "appnamespace not unique" in apolloconfig/apollo?

Check whether the app and its default namespace already exist before calling createDefaultAppNamespace (idempotency guard).

apolloconfig/apollo · error · ServiceException

appnamespace not unique

Error message

appnamespace not unique

What it means

A ServiceException (HTTP 500) thrown from AppNamespaceService.createDefaultAppNamespace() when the default 'application' namespace (ConfigConsts.NAMESPACE_APPLICATION) already exists for the given appId. The uniqueness check isAppNamespaceNameUnique() queries appNamespaceRepository.findByAppIdAndName(). This is called during initial app creation to bootstrap the mandatory default namespace; a duplicate means the app was already partially or fully initialized.

Source

Thrown at apollo-biz/src/main/java/com/ctrip/framework/apollo/biz/service/AppNamespaceService.java:108

  public AppNamespace findOne(String appId, String namespaceName) {
    Preconditions.checkArgument(!StringUtils.isContainEmpty(appId, namespaceName),
        "appId or Namespace must not be null");
    return appNamespaceRepository.findByAppIdAndName(appId, namespaceName);
  }

  public List<AppNamespace> findByAppIdAndNamespaces(String appId, Set<String> namespaceNames) {
    Preconditions.checkArgument(!Strings.isNullOrEmpty(appId), "appId must not be null");
    if (namespaceNames == null || namespaceNames.isEmpty()) {
      return Collections.emptyList();
    }
    return appNamespaceRepository.findByAppIdAndNameIn(appId, namespaceNames);
  }

  @Transactional
  @ApolloAuditLog(type = OpType.CREATE, name = "AppNamespace.createDefault")
  public void createDefaultAppNamespace(String appId, String createBy) {
    if (!isAppNamespaceNameUnique(appId, ConfigConsts.NAMESPACE_APPLICATION)) {
      throw new ServiceException("appnamespace not unique");
    }
    AppNamespace appNs = new AppNamespace();
    appNs.setAppId(appId);
    appNs.setName(ConfigConsts.NAMESPACE_APPLICATION);
    appNs.setComment("default app namespace");
    appNs.setFormat(ConfigFileFormat.Properties.getValue());
    appNs.setDataChangeCreatedBy(createBy);
    appNs.setDataChangeLastModifiedBy(createBy);
    appNamespaceRepository.save(appNs);

    auditService.audit(AppNamespace.class.getSimpleName(), appNs.getId(), Audit.OP.INSERT,
        createBy);
  }

  @Transactional
  public AppNamespace createAppNamespace(AppNamespace appNamespace) {
    String createBy = appNamespace.getDataChangeCreatedBy();
    if (!isAppNamespaceNameUnique(appNamespace.getAppId(), appNamespace.getName())) {

View on GitHub (pinned to d95fc18d11)

Solutions

Check whether the app and its default namespace already exist before calling createDefaultAppNamespace (idempotency guard).
If the app already exists with its default namespace, treat the error as benign and skip re-creation.
Use the isAppNamespaceNameUnique() check before invoking creation.
Investigate partial-failure cleanup if the app creation transaction is not atomic.

Example fix

// before: unconditional creation
appService.save(app);
appNamespaceService.createDefaultAppNamespace(app.getAppId(), operator);

// after: check before creating
if (appNamespaceService.isAppNamespaceNameUnique(app.getAppId(), "application")) {
    appNamespaceService.createDefaultAppNamespace(app.getAppId(), operator);
}

Defensive patterns

Strategy: validation

Validate before calling

// Check before creating the default namespace
if (appNamespaceService.isAppNamespaceNameUnique(appId, ConfigConsts.NAMESPACE_APPLICATION)) {
    appNamespaceService.createDefaultAppNamespace(appId, createBy);
} else {
    // default namespace already exists — app may be partially initialized
    logger.info("Default namespace already exists for app {}", appId);
}

Prevention

Make app-creation flows idempotent by checking for existing default namespace first.
Avoid retrying app-creation requests without verifying partial completion.
Use isAppNamespaceNameUnique() as a pre-check before any default-namespace creation.

When it happens

Trigger: createDefaultAppNamespace(appId, createBy) is called (typically during App creation) when an AppNamespace row already exists for appId + name='application'. This can happen if the app-creation flow is retried or if the namespace was created out-of-band.

Common situations: App creation request retried after a partial failure (app row committed but the error was returned to client); a database restore that left the namespace in place while the client re-ran creation; race condition between two concurrent app-creation requests; manual database intervention that pre-created the namespace.

Related errors

AI-assisted analysis of apolloconfig/apollo@d95fc18d11 (2026-08-14). Data as JSON: /api/errors/f90c8f1d7c72ecc3. Report an issue: GitHub.