What causes "Failed to bind address" in influxdata/influxdb?

Free the port: find and stop the process using it (`lsof -i :8181` / `ss -ltnp`).

influxdata/influxdb · error · Error

Failed to bind address

Error message

Failed to bind address

What it means

A serve-command `Error` variant (`BindAddress`) with a `std::io::Error` source, returned when the HTTP server cannot bind to the configured listen address. The most common underlying cause is the port already being in use, or lacking permission to bind the address/port.

Solutions

Free the port: find and stop the process using it (`lsof -i :8181` / `ss -ltnp`).
Bind to a different `--http-bind-address` port.
Use an unprivileged port or run with appropriate permissions; verify the host/IP is valid.

Example fix

// before
influxdb3 serve --http-bind-address 0.0.0.0:8181  # port already in use
// after
influxdb3 serve --http-bind-address 0.0.0.0:8182

Defensive patterns

Strategy: validation

Validate before calling

use std::net::TcpListener;
assert!(TcpListener::bind(("0.0.0.0", 8181)).is_ok(), "port 8181 already in use");

Try / catch

match serve(config) {
    Err(serve::Error::BindAddress(io)) if io.kind() == std::io::ErrorKind::AddrInUse => {
        eprintln!("port in use; pick another --http-bind-address");
    }
    Err(e) => return Err(e.into()),
    Ok(_) => {}
}

Prevention

Pre-flight check the bind port before starting serve
Use distinct ports per instance in dev/docker environments
Never bind privileged ports without appropriate capabilities

When it happens

Trigger: `influxdb3 serve` tries to bind the HTTP (or gRPC/trace) listener address and the OS refuses — EADDRINUSE, EACCES on privileged ports, or invalid bind address.

Common situations: Another influxdb3 instance still running on the default 8181 port; binding to a port <1024 without root; binding to an IP not assigned to the host; leftover docker container holding the port.

Related errors

AI-assisted analysis of influxdata/influxdb@06200ef96b (2026-09-19). Data as JSON: /api/errors/f81772281e0a5274. Report an issue: GitHub.

Appendix: source

Thrown at influxdb3/src/commands/serve.rs:126

const MIN_SNAPSHOTS_TO_LOAD_ON_START: u64 = 100;

mod cli_params;
#[cfg(test)]
mod tests;

#[derive(Debug, Error)]
pub enum Error {
    #[error("Cannot parse object store config: {0}")]
    ObjectStoreParsing(#[from] influxdb3_clap_blocks::object_store::ParseError),

    #[error("Tracing config error: {0}")]
    TracingConfig(#[from] trace_exporters::Error),

    #[error("Error initializing tokio runtime: {0}")]
    TokioRuntime(#[source] std::io::Error),

    #[error("Failed to bind address")]
    BindAddress(#[source] std::io::Error),

    #[error("Server error: {0}")]
    Server(#[source] influxdb3_server::Error),

    #[error("Token error: {0}")]
    TokenError(CatalogError),

    #[error("Write buffer error: {0}")]
    WriteBuffer(#[from] influxdb3_write::write_buffer::Error),

    #[error("invalid token: {0}")]
    InvalidToken(#[from] hex::FromHexError),

    #[error("failed to initialize write buffer: {0:?}")]
    WriteBufferInit(#[source] anyhow::Error),

    #[error("failed to initialize catalog: {0}")]

View on GitHub (pinned to 06200ef96b)