Troubleshooting Connections

What to check when KafkIO can't connect to a cluster, loses a connection it had, or connects but shows less than you expected. KafkIO has four places that help: the error dialog itself, the Network Tool, the Health Log and the Event Log (with the log files behind it). This page shows what each one tells you, then goes through the usual causes.

Where to start

Start with Test Connection

Test a cluster's settings in the Cluster Properties dialog before you save it: Test Connection at the bottom of every tab tests the Kafka cluster, and the second button next to it tests the service on the tab you're on (Test Schema Registry, Test Kafka Connect or Test ksqlDB). Testing a configuration shows where they are. Each test uses the dialog as it is now, so you can change a field and test again without saving.

• Test one thing at a time. Get Test Connection to succeed with the Kafka settings alone, then switch on Schema Registry, Kafka Connect or ksqlDB and test each of those. They're separate services with their own URLs, logins and certificates, and a problem with one doesn't stop KafkIO connecting to Kafka.
• Know what success proves. The Kafka test creates a client with your bootstrap servers, security settings and timeouts, and lists the topics. If it says A connection was successfully made!, the network path, the listener and your login all work. It doesn't prove you may read every topic or see every consumer group: the brokers decide that as you use them (see Limited permissions).
• Connecting gives the same errors. When you connect a saved cluster from the Kafka Clusters list, a failure shows the same dialogs as the test, so everything below applies to both.

Reading connection errors

Every error in KafkIO comes in the same Exception Details dialog. Its title says what KafkIO was doing (Error connecting and Timeout error connecting for a test or a connect; Error retrieving topic list. or Error retrieving messages once you're working with a cluster), and the line under it is the underlying error: the Java exception's name, then its message. That second part is the one to read.

1 2 3

1. Show Details (here already open, so it reads Hide Details) shows the full stack trace. The first lines say little; look further down for a Caused by: line, which often names the real problem.
2. Report opens KafkIO's bug-report form with the stack trace already in it. Use it when the error looks like a fault in KafkIO rather than in your settings; you can edit the text before you send it.
3. View Logs opens KafkIO's current log file in your text editor. It has the Kafka client's own messages, which are often more specific than the dialog (see The Event Log and log files).

The messages you're most likely to meet, and where each is explained:

Timeouts

A Kafka client that gets no usable answer from a broker can't tell why, so it keeps trying until its timeout runs out and then reports Timed out waiting for a node assignment. A closed port, the wrong security settings and a broken advertised listener all end the same way, which is why the Timeout error connecting dialog starts with Kafka cluster timeout errors can be misleading and has a Network Tool link (Timeouts and misconfiguration shows it). Work through the causes in this order:

1. Can you reach the port? Click Network Tool in the dialog and Check. If port open is false, nothing accepted a connection: wrong port, broker down, a firewall, or a network (VPN) you're not on. Fix that first; nothing else matters until it's true.
2. Do the security settings match that port? An open port with a timeout usually means the broker is ignoring what KafkIO sends: Plaintext against an SSL or SASL listener, or SSL against a plaintext one. Ask which listener (port) expects which security type.
3. Does the broker advertise an address you can reach? After the first contact the client is told each broker's address, and uses those. If View Logs shows Error connecting to node for a host or port you never entered (for example UnknownHostException: broker), the brokers' advertised.listeners are the problem. It's typical of Kafka in Docker, and of clusters behind a load balancer, NAT or a Kubernetes ingress.
4. Is it just slow? If the test sometimes works, or works on a second try, raise the timeouts in File ▸ Preferences ▸ Kafka. A cluster across the world or behind a busy VPN can need more than the defaults.

On a cluster with several brokers, one misconfigured broker may not stop KafkIO connecting, because the others answer. Instead, anything that needs that broker (the partitions it leads, for example) is slow or times out. If timeouts come and go with particular topics, check every broker's listeners, not just the bootstrap servers.

A timeout on a cluster that was working, such as the one in the screenshot above, usually means the cluster or the network went away: the Health Log will show it offline.

Checking reachability with the Network Tool

The Network Tool tells you, for each host and port, whether the name resolves to an IP address, whether the host answers a ping, and whether the port accepts a connection. It's the quickest way to separate a network problem from a configuration problem. Open it from:

• Tools ▸ Network Tool, which opens with an example row (google.ie, port 80) you can replace;
• Check network reachability under the Bootstrap servers field (or under a Schema Registry, Kafka Connect or ksqlDB URL), with those servers filled in;
• the Network Tool link in a Timeout error connecting dialog, with the cluster's bootstrap servers.

Checking reachability shows the window and how to read each result, and the Network Tool page has the rest. Two things to keep in mind when troubleshooting:

• An open port proves the network path, nothing more. It doesn't check the security settings or the brokers' advertised addresses; a timeout with an open port points at those.
• It connects directly, never through a proxy. A Schema Registry, Kafka Connect or ksqlDB URL that you can only reach through your HTTP proxy shows port open: false here even when KafkIO's own requests to it would work.

Using the Health Log

While a cluster is connected, KafkIO checks it in the background every 30 seconds (and once as it connects) and writes the result to the Health Log pane, below the cluster list. Show or hide it with View ▸ Health Log or Alt+3 (The Health Log describes the pane itself). It's the place to look when a cluster that worked starts failing, because it shows when it stopped answering and what error KafkIO got:

1 2 3

1. Status: offline, in red: the check failed. The time on the first red line is roughly when the cluster stopped answering.
2. Last error: what the check got back. A timeout here means KafkIO can't reach any broker any more; an authentication error suggests expired credentials or a changed password.
3. Topics (visible): how many topics your login can see. Fewer than you expect, on an online cluster, is a permissions question (see Limited permissions).

KafkIO doesn't disconnect a cluster that goes offline: it keeps checking every 30 seconds, so the log shows when the cluster answers again. Screens you open meanwhile fail with timeouts. If the cluster isn't coming back, disconnect it (see Connecting and disconnecting): while it stays connected, the Kafka client keeps retrying in the background and fills the log with messages about it.

The pane keeps the last 500 lines; untick Autoscroll health to scroll back through them without being pulled to the end every 30 seconds.

The Event Log and log files

Everything KafkIO and its Kafka clients log goes to a log file, and the same messages since KafkIO started are in the Event Log: Help ▸ View Event Log. When the error dialog is vague, these usually say which broker, address or step failed.

1 2 3 4

1. The line that matters here: the address the client tried (localhost/127.0.0.1:9192) and that it couldn't connect. Warnings have an exclamation-mark icon, information an i. With an advertised-listener problem, this is where you'd see an address you never entered.
2. Copy Log copies the whole log to the clipboard. To copy only some entries, select them and press Ctrl+C, or right-click one and choose Copy log entry.
3. Clear Log empties this window (not the log file), so that you can repeat what failed and see only the new messages.
4. Report Issue opens the bug-report form with the log in it.

Log files

The log files keep more than one session, so they're what to look at (or send) for a problem that happened earlier. View Logs in an error dialog opens the newest one, and Tools ▸ Show Logs In opens the folder in a Terminal or File Browser, or the newest file in a Text Editor (Config & Log Files). The folder is:

Files are named by date, kafkio_2026-10-24_3.log for example. KafkIO starts a new file every time it starts, every day and whenever the current one reaches 20 MB, and keeps the 20 most recent. By default it logs at INFO level; for more detail (the Kafka client's DEBUG messages, for example), start KafkIO from a terminal with the --debug option (Command-Line Options), repeat what failed, then look at the newest file.

Proxies and corporate networks

KafkIO talks to Kafka brokers directly, with Kafka's own protocol: the proxy settings never apply to broker connections. If the brokers are only reachable from inside your organisation's network, you need to be on that network (or its VPN), and the Network Tool's port open tells you whether you are.

A proxy is used only for HTTP: the check for new versions, and the Schema Registry, Kafka Connect and ksqlDB endpoints on which you've ticked Use proxy (if configured). You set it up once, under File ▸ Preferences ▸ Network:

1 2 3 4 5

1. Custom proxy switches the proxy on, as HTTP or SOCKS. Auto-detect (top right) looks up the proxy your system or browser is set to use and fills in the fields; click it again to cycle through them if it found more than one.
2. Hostname and Port of the proxy. Tick Proxy requires authentication for a username and password. If you untick Persist password between sessions, KafkIO asks for the password each time it starts.
3. Check connection tries to fetch a public website through the proxy and says whether it worked. It proves the proxy settings, not that your internal endpoints are reachable through it.
4. Also set JDK proxy system properties: for OAuth sign-ins that fetch tokens over HTTP and can't be given a proxy any other way (the note names Strimzi, AWS IAM, Azure Event Hubs and Kafka's own OAuth libraries). Leave it off unless such a sign-in fails behind a proxy; restart KafkIO after changing it if you've already connected to clusters.
5. Accept non-trusted certificates automatically: see the next section.

Typical proxy problems:

• A REST endpoint times out or can't be resolved from the office, but works at home (or the other way round): tick or untick Use proxy (if configured) on that endpoint's tab. Internal endpoints usually must not go through the proxy; public ones (Confluent Cloud, Aiven) often must.
• UnknownHostException naming your proxy: an endpoint still has Use proxy (if configured) ticked for a proxy you no longer use. Schema Registry uses the proxy's host and port whenever that box is ticked, even with Custom proxy switched off (Schema Registry: using a proxy).
• Schema Registry fails through a proxy that needs a password: KafkIO passes only the proxy's host and port to the Schema Registry client, so a proxy that requires authentication doesn't work for Schema Registry. Kafka Connect and ksqlDB get the username and password too.
• An OAuth sign-in to the brokers fails behind a proxy: the token endpoint is fetched over HTTP, so try Also set JDK proxy system properties 4.

Self-signed certificates on REST endpoints

Schema Registry, Kafka Connect and ksqlDB on https:// URLs often use a certificate from an internal certificate authority, or a self-signed one. How KafkIO decides whether to trust it depends on the endpoint's Truststore file field:

• Truststore file set on the endpoint's tab: KafkIO trusts what's in that file and nothing else. A PKIX path building failed or SSLHandshakeException means the file doesn't hold the certificate (or the CA that signed it) for that server. See TLS for Schema Registry (Connect and ksqlDB work the same way).
• Truststore file blank: KafkIO uses the trust set under File ▸ Preferences ▸ Network ▸ SSL configuration. Accept non-trusted certificates automatically is ticked by default, which accepts any certificate, so a blank truststore normally just works. With it unticked, KafkIO trusts the certificate authorities Java trusts, plus the certificates you add to the list below it with Add certificate; add your internal CA's certificate (or the server's self-signed one) there, once, for the Schema Registry and Kafka Connect endpoints of every cluster. ksqlDB doesn't use that list: with the box unticked and its truststore blank, it trusts only Java's certificate authorities, so give a ksqlDB server with an internal certificate a truststore on its tab.

KafkIO asks you to restart after you change the SSL configuration (SSL configuration changed), because the trust is set up when it starts. Ticking SSL validation on an endpoint's tab adds a host name check: the certificate must also be issued for the host in the URL (Hostname validation).

Docker and advertised listeners

The classic local failure: Kafka runs in Docker on your machine, Test Connection to localhost:9092 times out, yet the Network Tool says the port is open. The broker answered the first contact and told KafkIO to use the address in its advertised.listeners, typically the container's name (broker:9092), which only resolves inside Docker's network. The log shows it as Error connecting to node broker:9092 with UnknownHostException: broker.

The fix is on the broker, not in KafkIO: advertise an address that KafkIO can reach (for KafkIO on the same machine, localhost and the port published by the container), and bind the listener to 0.0.0.0 inside the container. Kafka in Docker explains both settings and the two-listener setup for clients inside and outside Docker, and Tools ▸ Sample Docker Compose gives you a compose file that already works (Sample Docker Compose). The same thing happens with Kafka on Kubernetes, behind NAT, or on a cloud VM that advertises its private address; see Provider Recipes for specific platforms.

Limited permissions

When a cluster enforces ACLs, KafkIO can only show what your login may see. It doesn't tell you up front that something is hidden: things you aren't allowed to describe are simply left out, and actions you aren't allowed to take fail when you try them. In the lab, a user who may use some of the cluster's topics but has no permission on the cluster itself saw this on the Brokers page:

1 2 3

1. Controller Type is Unknown: KafkIO couldn't ask the cluster whether it runs KRaft or ZooKeeper.
2. Disk Usage is N/A: describing the brokers' log directories was refused.
3. For the same reason, the Log Dirs tab is empty and says No log directories to display (maybe due to lack of permissions)...

Elsewhere, for the same user:

None of this is a fault in KafkIO or in your connection settings: it's your login's ACLs. If you need more, ask your Kafka administrator for the operations you're missing (typically Describe on the topics and groups you should see, Read on the topics you browse, and Describe on the cluster for broker details). If you can view ACLs yourself, the Access Control Lists page shows how to check which apply to you.

Related

• General Connection Settings
• Security & Authentication
• Provider Recipes
• Network Tool
• Network, Proxy & Trust
• Kafka & Timeouts
• Getting Help & Reporting Issues