Fixing ClickHouse Port 8123 Connection Refused Errors

Hey guys! Ever run into that super frustrating “connection refused” error when trying to connect to your ClickHouse instance on port 8123? Yeah, we’ve all been there. It’s like hitting a brick wall when you’re just trying to get some data analysis done. But don’t sweat it! This article is your go-to guide for tackling the ClickHouse port 8123 connection refused problem head-on. We’ll break down why this happens and, more importantly, how to fix it so you can get back to querying like a boss.

Understanding the “Connection Refused” Error

So, what exactly is this dreaded ClickHouse port 8123 connection refused message trying to tell you? Basically, when your client application tries to establish a connection to the ClickHouse server on port 8123, the server (or something in between) is actively rejecting that connection attempt. It’s not that the server is down or unreachable; it’s specifically saying, “Nope, not accepting connections on this port from you right now.” This usually points to a configuration issue on the ClickHouse server itself, or a network problem preventing the connection from reaching the intended service. It’s important to differentiate this from a timeout error, where the request just never gets a response. With “connection refused,” you get an immediate, definitive rejection, which is actually a good thing because it narrows down the potential causes significantly. Think of it like trying to knock on a door, and instead of silence, the door immediately slams shut in your face. That’s the server telling you it’s not ready or willing to let you in on that specific port. We’ll dive into the common culprits in the next sections, but knowing this fundamental difference is key to troubleshooting.

Common Causes for ClickHouse Port 8123 Issues

Alright, let’s get down to the nitty-gritty of why you might be seeing that ClickHouse port 8123 connection refused error. There are a few usual suspects that pop up time and again. First off, is ClickHouse even running? It sounds obvious, but sometimes services can stop unexpectedly, especially after a server reboot or if there was a crash. You need to make sure the ClickHouse server process is actually active and listening on port 8123. Another big one is the network configuration. Even if ClickHouse is running, it might not be configured to listen on the network interface you’re trying to connect from. By default, ClickHouse might be set to listen only on localhost (127.0.0.1), which means it’s only accepting connections from the machine it’s running on. If you’re trying to connect from a different machine, you’ll get that dreaded refusal. Firewall rules are also a frequent offender. Your server’s firewall (like iptables or ufw on Linux) might be blocking incoming connections to port 8123. Similarly, cloud providers often have their own security groups or network ACLs that need to be configured to allow traffic on that port. Lastly, there’s the ClickHouse configuration file itself. The listen_host directive in the ClickHouse configuration ( config.xml or users.xml ) dictates which IP addresses the server will bind to. If this isn’t set correctly to accept external connections, you’re going to have a bad time. We’ll explore how to check and fix each of these in the following sections, so stay tuned!

Checking if ClickHouse is Running

First things first, guys, let’s confirm that your ClickHouse server is actually up and running. It sounds super basic, but you’d be surprised how often the simplest check resolves the ClickHouse port 8123 connection refused issue. On most Linux systems, you can use systemctl to check the status of the ClickHouse service. Just open up your terminal and type:

sudo systemctl status clickhouse-server

If it’s active and running, you’ll see a green active (running) status. If it’s inactive or failed, you’ll need to start or restart it using:

sudo systemctl start clickhouse-server

And to make sure it starts automatically on boot:

sudo systemctl enable clickhouse-server

Another crucial check is to see if any process is actually listening on port 8123. You can use netstat or ss for this. Try:

sudo netstat -tulnp | grep 8123

Or the more modern ss command:

sudo ss -tulnp | grep 8123

If you see output showing a process (ideally clickhouse-server ) listening on 0.0.0.0:8123 or a specific IP address, that’s a good sign! If you don’t see any output, it strongly suggests that ClickHouse isn’t listening on that port, which brings us back to checking the service status and its configuration. This step is absolutely fundamental. Without a process actively listening, no connection will ever be accepted, leading directly to that ClickHouse port 8123 connection refused error. So, make sure this check passes before moving on to more complex network troubleshooting.

Verifying Network Bindings

Okay, so ClickHouse is running, and it should be listening on port 8123. But why the ClickHouse port 8123 connection refused error? The next big thing to check is where ClickHouse is configured to listen. By default, for security reasons, many applications, including ClickHouse, might be set up to only accept connections from the local machine (localhost). This is controlled by the listen_host setting in your ClickHouse configuration file. You’ll typically find this file at /etc/clickhouse-server/config.xml or sometimes in /etc/clickhouse-server/users.xml or included files. Open this file in your favorite text editor (with sudo privileges, of course):

sudo nano /etc/clickhouse-server/config.xml

Look for a line that looks something like this:

<listen_host>::</listen_host>

What does this mean, you ask? Well, <listen_host>::</listen_host> or <listen_host>0.0.0.0</listen_host> tells ClickHouse to listen on all available network interfaces. This is usually what you want if you need to connect from other machines. If you see <listen_host>127.0.0.1</listen_host> , ClickHouse is only listening for connections originating from the server itself. If this is the case, and you’re connecting remotely, you’ve found your culprit for the ClickHouse port 8123 connection refused error! To fix it, change 127.0.0.1 to 0.0.0.0 (or :: for IPv6, which often covers both) and then restart the ClickHouse server for the changes to take effect:

sudo systemctl restart clickhouse-server

After restarting, re-run the netstat or ss command from the previous step to confirm it’s now listening on 0.0.0.0:8123 or :::8123 . This is a super common reason for remote connection failures, so double-checking this setting is crucial. Sometimes, you might have multiple <listen_host> entries or includes, so make sure you’re checking the effective configuration that’s being applied.

Checking Firewall Rules

Alright, so you’ve confirmed ClickHouse is running and configured to listen on all interfaces ( 0.0.0.0 ). Yet, you’re still getting that annoying ClickHouse port 8123 connection refused error. What gives? The next major suspect is your firewall. Firewalls are designed to protect your server by controlling network traffic, but they can also inadvertently block legitimate connections if not configured properly. We need to make sure that incoming connections on port 8123 are allowed.

Linux Firewalls (iptables/ufw)

If you’re using a Linux server, you’re likely dealing with iptables or ufw (Uncomplicated Firewall), which is a simpler frontend for iptables . Let’s check ufw first, as it’s more common on Ubuntu/Debian-based systems.

To check the status of ufw :

sudo ufw status

If ufw is active, you’ll see a list of rules. Look for port 8123. If it’s not listed as allowed, you need to add a rule:

sudo ufw allow 8123/tcp

Then, reload the firewall rules:

sudo ufw reload

If you’re using iptables directly, the commands are a bit different. To check existing rules:

sudo iptables -L INPUT -n --line-numbers

Look for any rule that might be DROP ing or REJECT ing traffic on tcp dpt:8123 . If you don’t see an explicit ACCEPT rule for port 8123, you’ll need to add one. Be careful here, as iptables rules are processed in order. A common way to add it to allow incoming TCP traffic on port 8123 is:

sudo iptables -I INPUT -p tcp --dport 8123 -j ACCEPT

Note: iptables rules added this way are often not persistent across reboots. You might need to use tools like iptables-persistent to save them. This step is critical because even if ClickHouse is configured correctly, the OS firewall can completely block access, manifesting as a ClickHouse port 8123 connection refused error because the connection never even reaches the ClickHouse process.

Cloud Provider Firewalls (Security Groups/Network ACLs)

If your ClickHouse server is hosted on a cloud platform like AWS, Google Cloud, or Azure, you also need to check the network security rules configured at the cloud provider level. These act as an additional layer of network filtering before traffic even reaches your server’s operating system firewall.

• AWS: Check your Security Groups . Find the security group associated with your EC2 instance running ClickHouse. Ensure there’s an inbound rule allowing TCP traffic on port 8123 from the IP addresses or CIDR ranges you expect your clients to connect from. Be specific with your source IP ranges for better security.
• Google Cloud: Check your VPC Network Firewall Rules . Similar to AWS, you need to create a firewall rule that allows ingress (incoming) traffic on TCP port 8123 to your ClickHouse VM instances. Specify the correct network tags and source IP ranges.
• Azure: Check your Network Security Groups (NSGs) . Go to the NSG associated with your virtual machine or subnet. Add an inbound security rule to allow TCP traffic on port 8123 from the appropriate source IPs.

Forgetting to configure these cloud-level firewalls is a very common reason for the ClickHouse port 8123 connection refused error when the server is running correctly locally. Always remember to apply changes and allow a minute or two for them to propagate across the cloud infrastructure.

Troubleshooting Remote Access Issues

So, we’ve covered the server running, the network bindings, and the firewalls. If you’re still facing the ClickHouse port 8123 connection refused error, especially when connecting from a different machine, let’s think about remote access specifics. Sometimes, the issue isn’t a direct block but a misunderstanding of how ClickHouse is exposed.

Connecting via Proxy or Load Balancer

In many production environments, you won’t connect directly to the ClickHouse server’s IP address. Instead, you might be going through a proxy (like Nginx or HAProxy) or a load balancer. If this is the case, the ClickHouse port 8123 connection refused error could stem from the proxy/load balancer configuration:

• Proxy Configuration: Ensure your proxy is correctly configured to forward traffic to the ClickHouse server’s IP address and port 8123. Check the proxy’s logs for any errors. Make sure the proxy itself is running and accessible.
• Load Balancer: If you’re using a load balancer, verify that the ClickHouse nodes are registered as healthy backends and that the load balancer’s listener is configured for port 8123. Check the load balancer’s health checks; if they are failing for ClickHouse, it won’t send traffic its way.
• Network Between Proxy and ClickHouse: Even if the proxy is configured correctly, there might be network issues or firewalls between the proxy/load balancer and the actual ClickHouse server. Ensure this segment of the network is also open.

This is often overlooked because the focus tends to be solely on the ClickHouse server itself. But if there’s an intermediary, it becomes a critical part of the connection path.

Using ClickHouse Client Tools

When testing connectivity, using the official clickhouse-client is a great way to isolate the problem. If you can connect using the client from the same machine where ClickHouse is running, but not remotely, it strongly points towards network or firewall issues we’ve already discussed. If the client gives you a ClickHouse port 8123 connection refused error even when run locally (and ClickHouse is supposedly running), double-check the listen_host and service status.

To test remotely with clickhouse-client :

clickhouse-client --host <your_clickhouse_ip> --port 8123 --user default

Replace <your_clickhouse_ip> with the actual IP address of your ClickHouse server. If this fails with