floci-io/floci · error · IllegalStateException

No free ports in range " + basePort + "-" + maxPort

Error message

No free ports in range " + basePort + "-" + maxPort

What it means

Thrown by core/common/port/PortAllocator.allocate (the package-private, in-use-set based allocator, distinct from the docker PortAllocator) when every port in [basePort, maxPort] is already in the inUse set. This allocator does not probe the OS — it only tracks ports it handed out, and ports are returned via release(port).

Source

Thrown at src/main/java/io/github/hectorvent/floci/core/common/port/PortAllocator.java:39

    @Inject
    public PortAllocator(EmulatorConfig config) {
        this(config.services().lambda().runtimeApiBasePort(),
                config.services().lambda().runtimeApiMaxPort());
    }

    PortAllocator(int basePort, int maxPort) {
        this.basePort = basePort;
        this.maxPort = maxPort;
    }

    public int allocate() {
        for (int p = basePort; p <= maxPort; p++) {
            if (inUse.add(p)) {
                return p;
            }
        }
        throw new IllegalStateException(
                "No free ports in range " + basePort + "-" + maxPort);
    }

    public void release(int port) {
        inUse.remove(port);
    }
}

View on GitHub (pinned to 62ff490619)

Solutions

1. Increase the configured port range for the affected subsystem
2. Ensure resources are deleted/closed so their ports are released before allocating more
3. Restart floci to reset the in-use set if allocations leaked
4. Reduce the number of concurrently open emulated TCP resources

Example fix

# before
floci.rds.port-range: 45000-45010

# after
floci.rds.port-range: 45000-45200

boolean canAllocate(PortAllocator allocator, int count, int span) {
    return allocator.availableCount() + count <= span; // or track release() calls yourself
}

try {
    int port = allocator.allocate();
} catch (IllegalStateException e) {
    // in-use set full: release unused ports (delete resources) or widen range; restart resets set
}

When it happens

Trigger: Allocating more ports than the configured basePort..maxPort span without releasing them; leaking allocations (never calling release) across many cycles; a too-narrow range for the number of simultaneous emulated listeners (e.g. RDS/ElastiCache TCP proxies).

Common situations: Creating and destroying many TCP-proxied resources in one emulator session where release is skipped on failure paths; a narrow default range combined with test parallelism; restart reserving many ports up front.

Related errors

• No free port available in range ${basePort}-${maxPort}
• floci.storage.efs owner-uid and owner-gid must be set togeth
• floci.storage.efs root-permissions must be 3-4 octal digits
• Could not find a free port
• Unknown storage mode: " + mode

AI-assisted analysis of floci-io/floci@62ff490619 (2026-08-14). Data as JSON: /api/errors/af75dbfd293666f5. Report an issue: GitHub.