Introduction
Testing a connection is the first step when an extract or connector setup is not working in Kleene. Connection problems are best narrowed down in stages: can the server be reached, do the credentials work, can metadata be fetched, can the extract load complete?
Issue description
A connection can fail at several points: during setup, metadata fetching, extract creation, execution or warehouse loading. Separate the connection into stages so you can identify where the failure occurs. A source may be reachable but still have invalid credentials. Credentials may also work but not have access to the required schemas or tables.
Signs
Common signs of a connection problem include source metadata not loading, schemas or tables not appearing, the connector timing out, an extract starting but failing before producing data, or an error that points to networking, authentication, permissions, or metadata access.
Basic troubleshooting steps
Use the checklist below to rule out the most common causes before moving to deeper investigation.
- Confirm the server is reachable from the network Kleene is using.
- Test the port and confirm the hostname, IP address, and firewall or allowlisting rules.
- Validate the credentials outside Kleene.
- Confirm the user can access the required databases, schemas, and tables.
- Check whether metadata can be fetched successfully.
- Run a test extract.
- Confirm the data lands in the filestore.
- Confirm the warehouse load completes.
Common causes and how to fix them
Server cannot be reached
If the server cannot be reached, the connector will fail before credentials or permissions can be properly tested. This usually points to networking, VPN, firewall, hostname, port, or IP allowlisting.
How to fix it: test reachability with a ping on the server. If the connection fails, ask to validate IP allowlisting, firewall rules, hostname, port, and network access.
Credentials are incorrect
If the server can be reached but metadata cannot be fetched, credentials may be invalid or incomplete. This can happen after password changes, credential rotation, copy/paste mistakes, or when the wrong connector type is used.
How to fix it: test the same credentials in a database IDE such as DBeaver, making sure the test is run from the correct network or VPN where required. Also check for hidden spaces or non-printing characters in usernames, passwords, hostnames, and database names.
Connector type is wrong
A connection can fail if the credentials are added to the wrong connector type. For example, MSSQL credentials will not work correctly in a MySQL connector.
How to fix it: confirm the source technology first, then check that the connector type matches the source system.
Permissions are incomplete
Credentials can be valid but still lack access to the databases, schemas, or tables needed by the extract. In this case, connection may succeed but metadata may be incomplete or extracts may fail later.
How to fix it: confirm that the user can see the required objects in metadata. If objects are missing, ask to grant access to the required databases, schemas, and tables.
Practical troubleshooting workflow
- Confirm the source system and connector type.
- Check whether the server can be reached using the hostname/IP and port.
- If reachability fails, ask to validate IP allowlisting, firewall, port, VPN, and network access.
- If reachability works, test the credentials in an IDE such as DBeaver.
- Check for spelling mistakes, accidental spaces, wrong ports, and invalid SSH files.
- Confirm whether metadata can be fetched.
- Confirm whether the required databases, schemas, and tables are visible.
- Create and run a simple test extract.
- Confirm whether extracted data lands in filestore.
- Confirm whether the load completes into the warehouse.
- Use the stage where the process fails to decide whether the issue is networking, credentials, permissions, extraction, or warehouse loading.
Additional information
A useful way to approach source connection troubleshooting is to ask five questions:
- Can Kleene see the server?
- Do the credentials work?
- Can the connector fetch metadata?
- Did the extract complete and land data in filestore?
- Did the load complete into the data warehouse?
The answer to these questions usually identifies where the issue sits and what to investigate next.