grpc/grpc-java · error · IOException

name already registered:

Error message

name already registered: 

What it means

InProcessServer.registerInstance places the server into the global in-process registry keyed by name; if the name is already taken by another running server it throws IOException 'name already registered: <name>'. Only one server can own a given in-process name at a time.

Solutions

1. Shut down the existing server with that name before starting a new one.
2. Use InProcessServerBuilder.generateName() for a unique name per server instance.
3. Catch IOException from server.start() and fall back to another name, or use a directExecutor-free retry with a fresh name.

Example fix

// before
// two servers, same name
Server s1 = InProcessServerBuilder.forName("svc").addService(...).build().start();
Server s2 = InProcessServerBuilder.forName("svc").addService(...).build().start(); // IOException
// after
Server s1 = InProcessServerBuilder.forName("svc").addService(...).build().start();
s1.shutdownNow();
Server s2 = InProcessServerBuilder.forName("svc").addService(...).build().start();

if (InProcessServerRegistry as seen by a prior server still has the name) prefer generateName() or shut down the old server first;

try { server.start(); } catch (IOException e) { if (e.getMessage().startsWith("name already registered")) { priorServer.shutdownNow(); server.start(); } else { throw e; } }

When it happens

Trigger: Starting a second InProcessServer with InProcessServerBuilder.forName("same-name") while a server with that name is still registered (not shut down).

Common situations: Test suites starting servers per test without shutting them down or deregistering; duplicate server startup in the same JVM after a failed teardown; two app modules registering the same service name.

Related errors

• AnonymousInProcessSocketAddress is not serializable
• call forName() instead
• call forName() instead
• Server instance already registered
• The transport factory is closed.

AI-assisted analysis of grpc/grpc-java@64daddc1f3 (2026-09-08). Data as JSON: /api/errors/d313d27ebca18040. Report an issue: GitHub.

Appendix: source

Thrown at inprocess/src/main/java/io/grpc/inprocess/InProcessServer.java:89

    this.streamTracerFactories =
        Collections.unmodifiableList(checkNotNull(streamTracerFactories, "streamTracerFactories"));
  }

  @Override
  public void start(ServerListener serverListener) throws IOException {
    this.listener = serverListener;
    this.scheduler = schedulerPool.getObject();
    // Must be last, as channels can start connecting after this point.
    registerInstance();
  }

  private void registerInstance() throws IOException {
    if (listenAddress instanceof AnonymousInProcessSocketAddress) {
      ((AnonymousInProcessSocketAddress) listenAddress).setServer(this);
    } else if (listenAddress instanceof InProcessSocketAddress) {
      String name = ((InProcessSocketAddress) listenAddress).getName();
      if (registry.putIfAbsent(name, this) != null) {
        throw new IOException("name already registered: " + name);
      }
    } else {
      throw new AssertionError();
    }
  }

  @Override
  public SocketAddress getListenSocketAddress() {
    return listenAddress;
  }

  @Override
  public List<? extends SocketAddress> getListenSocketAddresses() {
    return Collections.singletonList(getListenSocketAddress());
  }

  @Override
  public InternalInstrumented<SocketStats> getListenSocketStats() {

View on GitHub (pinned to 64daddc1f3)