Diagnosing SQL Developer Connection Test Failures

Recognizable condition

When you click Test in a SQL Developer connection, the dialog returns an error instead of Status: Success. Common messages include network timeouts, ORA‑01017, ORA‑28759, or generic IO errors.

Cause / diagnostic table

Symptom	Likely cause
Timeout or "IO Error: The Network Adapter could not establish the connection"	Network connectivity problem (host unreachable, firewall, wrong port)
Listener not registered for the SID/service name	Listener misconfiguration (down, bound to wrong IP/port, service not registered)
ORA‑01017: invalid username/password; logon denied	Authentication failure (bad credentials, expired/password locked)
ORA‑28759: failure to open file or ORA‑28890: SSL handshake failure	Wallet or TLS issues (missing wallet, wrong location, SSL version mismatch)
Intermittent failures only when VPN/proxy is active	Local firewall, VPN, or corporate proxy blocking outbound traffic to listener port

Ordered checks

1. Verify basic network reachability

   From the same workstation where SQL Developer runs, test TCP connectivity to the listener host and port (default 1521). Use telnet or nc (netcat).

   # Replace db-host and 1521 with your values
    telnet db-host 1521
    # or
    nc -zv db-host 1521
   

   Expected output: a successful TCP handshake (e.g., "Connected to db-host" or "succeeded!"). If the command hangs or returns "Connection refused" or "timeout", the network path is blocked.

2. Check listener status on the database server

   Ask the DBA to run lsnrctl status (or run it yourself if you have SSH access with appropriate privileges). Verify that the listener is listening on the expected IP/port and that the service name/SID you use appears in the Services Summary section.

   $ lsnrctl status
   LSNRCTL for Linux: Version 19.0.0.0.0 - Production
   ...
   Services Summary...
   Service "orcl" has 1 instance(s).
   Instance "orcl", status READY, has 1 handler(s) for this service...
   

   If the service is missing or the listener shows "Listening on: (DESCRIPTION=(ADDRESS=(PROTOCOL=tcp)(HOST=…)(PORT=1521)))" but the host/IP differs from what you used, the listener is bound to a different address.

3. Validate credentials

   Attempt a connection with SQL*Plus using the same username/password and connection string. This isolates SQL Developer from the issue.

   sqlplus username/password@//db-host:1521/service_name
   

   Success returns a SQL prompt; failure with ORA‑01017 indicates bad credentials or an expired/locked account.

4. Inspect wallet/TLS settings (if using TCPS)

   Check that sqlnet.ora on the client points to a valid wallet directory and that the wallet contains the required certificates.

   # Example sqlnet.ora snippet
   WALLET_LOCATION =
     (SOURCE =
       (METHOD = FILE)
       (METHOD_DATA =
         (DIRECTORY = /home/user/oracle/wallet)
       )
     )
   SSL_CLIENT_AUTHENTICATION = FALSE
   

   Test the TLS handshake with OpenSSL:

   openssl s_client -connect db-host:1521 -servername db-host -tls1_2
   

   Look for "Verify return code: 0 (ok)". Any other return code indicates a wallet or version mismatch.

5. Check local firewall/proxy

   Ensure outbound TCP to the listener port is allowed. On Linux, sudo iptables -L -v -n | grep 1521 shows rules; on Windows, review Windows Firewall with Advanced Security. If a corporate proxy is in place, confirm that it does not block non‑HTTP traffic to the database host.

Fixes tied to findings

• Network connectivity – Correct routing, open firewall ports, or adjust VPN split‑tunnel to allow traffic to db-host:1521. Retry the connection test.
• Listener misconfiguration – Have the DBA restart the listener (lsnrctl stop then lsnrctl start) or modify listener.ora to bind to the correct IP and register the service. After changes, run lsnrctl status to confirm.
• Authentication failure – Reset the password via SQL*Plus (ALTER USER username IDENTIFIED BY new_password;) or unlock the account (ALTER USER username ACCOUNT UNLOCK;). Use the new credentials in SQL Developer.
• Wallet/TLS issues – Ensure the wallet directory is readable by the OS user running SQL Developer, update sqlnet.ora with the correct DIRECTORY, and import any missing certificates. Verify with the OpenSSL test above.
• Firewall/proxy blocking – Add an outbound rule for TCP port 1521 to the destination host, or configure the proxy to allow the connection. Test again with telnet or nc.

Escalation criteria

If after completing the ordered checks the connection test still fails, escalate as follows:

• Persistent network timeouts despite open ports – involve the network team to inspect routing, NAT, or load‑balancer devices.
• Listener shows correct registration but SQL Developer still fails – ask the DBA to enable listener tracing (lsnrctl trace) and examine trace files for protocol errors.
• Wallet/TLS errors persist after verifying file paths and certificates – engage the security team to review the certificate chain and SSL/TLS version requirements.
• Repeated ORA‑01017 after credential reset – verify account profile limits, password lifetime, and whether the account is governed by an external authentication system (e.g., LDAP, Kerberos).

Limitations and practical verification

This guide assumes you are using the default Oracle listener port (1521) and that you have access to run basic network utilities from the client workstation. It does not cover exotic protocols such as IPC or SDP. After each corrective action, re‑run the Test button in SQL Developer; a successful test returns the banner Status: Success. Use the same command‑line checks (tnsping, telnet/nc, openssl s_client) from the exact machine where SQL Developer runs to confirm that the underlying issue is resolved before relying on the GUI test.