apache/cassandra · error · IllegalStateException

Missing port number

Error message

Missing port number

What it means

Thrown by Server.getSocket() when the Builder was never given a port, so no InetSocketAddress can be constructed. The builder defers socket creation until start time and throws an IllegalStateException rather than a build-time error if neither a socket nor (port) is set. This is a programming/configuration mistake in server setup code.

Solutions

1. Call Server.Builder.port(int) with the desired native transport port before building
2. Or pass a complete InetSocketAddress via the socket(...) builder method instead
3. Add a unit test constructing the server the same way production code does to catch this at CI time
4. Log/assert builder completeness before start() in embedding code

Example fix

// before
Server.builder().withHost(addr).build();
// after
Server.builder().withHost(addr).withPort(9042).build();

if (builderPort == -1) throw new IllegalArgumentException("Server.Builder requires a port; call port(...) or socket(...)");

boolean readyToBuild(Server.Builder b) { return b.getPort() != -1; }

try { server.start(); } catch (IllegalStateException e) { if (e.getMessage().equals("Missing port number")) { fixBuilderConfig(); } else throw e; }

When it happens

Trigger: Building a Server via Server.Builder with only a host address (or nothing) — port remains the default -1 — then calling getSocket()/start(); this.socket is null, this.port == -1 triggers the throw.

Common situations: Embedding Cassandra's transport in tests or tools and forgetting Builder.port(...), copying builder code and deleting the port line, or setting an InetSocketAddress field that is later cleared.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• Missing host
• be positive
• native_transport_min_backoff_on_queue_overload should be…
• a hints file cannot be configured for both compression and…
• A maximum number of tokens per node is supported

AI-assisted analysis of apache/cassandra@88fd0f6a0e (2026-09-10). Data as JSON: /api/errors/df8def9b1ac1870f. Report an issue: GitHub.

Appendix: source

Thrown at src/java/org/apache/cassandra/transport/Server.java:288

        public Builder withEventNotifier(EventNotifier eventNotifier)
        {
            this.eventNotifier = eventNotifier;
            return this;
        }

        public Server build()
        {
            return new Server(this);
        }

        private InetSocketAddress getSocket()
        {
            if (this.socket != null)
                return this.socket;
            else
            {
                if (this.port == -1)
                    throw new IllegalStateException("Missing port number");
                if (this.hostAddr != null)
                    this.socket = new InetSocketAddress(this.hostAddr, this.port);
                else
                    throw new IllegalStateException("Missing host");
                return this.socket;
            }
        }
    }

    public static class ConnectionTracker implements Connection.Tracker
    {
        private static final ChannelMatcher PRE_V5_CHANNEL = channel -> channel.attr(Connection.attributeKey)
                                                                               .get()
                                                                               .getVersion()
                                                                               .isSmallerThan(ProtocolVersion.V5);

        // TODO: should we be using the GlobalEventExecutor or defining our own?
        public final ChannelGroup allChannels = new DefaultChannelGroup(GlobalEventExecutor.INSTANCE);

View on GitHub (pinned to 88fd0f6a0e)