Diagnosing SQL Developer Connection Failures to Oracle Databases

Recognizable condition

SQL Developer displays a connection test failure with the message: Status: Failure - Test failed: IO Error: The Network Adapter could not establish the connection.

Cause / diagnostic table

Possible cause	Typical indicator
Incorrect hostname, port, or service name	Connection details do not match the database listener
Oracle listener not running or blocked by firewall	Listener service down or port inaccessible
Wallet or SSL configuration mismatch (TCPS)	Using TCPS protocol but wallet missing or invalid

Ordered troubleshooting checks

1. Verify network reachability
   1. Open a terminal (command prompt on Windows, shell on Linux/macOS).
   2. Run ping <hostname> to confirm DNS resolution. Note: ping may be blocked by ICMP firewall rules.
   3. Run telnet <hostname> <port> (default 1521 for TCP, 2484 for TCPS) to test TCP connectivity. If telnet is not installed, use nc -zv or PowerShell Test-NetConnection.
2. Check listener status
   1. On the database server, as a user with privileges to run lsnrctl, execute lsnrctl status.
   2. Look for the service name you are trying to connect to (e.g., ORCL) listed as Ready.
   3. If the listener is down, start it with lsnrctl start (requires OS admin or Oracle software owner).
3. Validate connection details in SQL Developer
   1. Open the connection definition (Tools → Preferences → Database → Connections or right‑click the connection → Properties).
   2. Confirm that Hostname, Port, and Service Name (or SID) match the values shown by lsnrctl status.
   3. If using TCPS, ensure the protocol is set to TCPS and the port matches the listener’s TCPS endpoint.
4. When using Oracle Wallet (TCPS)
   1. Locate the wallet directory referenced in the connection (or in sqlnet.ora if you have edited it).
   2. Confirm the directory contains a file named cwallet.sso (auto‑login wallet).
   3. Check that the wallet is not expired and contains the correct database credential (you can use mkstore -wrl <wallet_dir> -view as the wallet owner).

Fixes tied to findings

• Incorrect hostname/port/service name: Edit the connection in SQL Developer to correct the values, then click Test. Rollback: revert to the previous values if the test fails.
• Listener not running: Start the listener on the database host (lsnrctl start). Ensure the listener is configured to listen on the expected port (lsnrctl status shows Listening Endpoints Summary). Rollback: stop the listener with lsnrctl stop if you started it only for testing.
• Firewall block: Work with network admin to open the required TCP port (1521 for TCP, 2484 for TCPS) between the client machine and the database server. Rollback: close the port after testing if it was opened temporarily.
• Wallet/SSL mismatch: Ensure the wallet location is correctly referenced, the cwallet.sso file exists, and the sqlnet.ora (if used) points to the wallet via WALLET_LOCATION = (SOURCE = (METHOD = FILE)(METHOD_DATA = (DIRECTORY = <wallet_dir>))). If using TCPS, verify the listener has a TCPS endpoint and the client uses the same port. Rollback: restore the previous wallet location or sqlnet.ora settings.

Escalation criteria

• Network reachability tests (ping/telnet) succeed but the listener status shows the service is not registered or the listener is down despite start attempts.
• After correcting connection details and verifying listener, the test still fails with the same IO error.
• Wallet file is present but mkstore reports errors or the wallet cannot be opened.
• In these cases, gather the following information and open a support ticket with the DBA team or Oracle Support:
• Output of lsnrctl status and lsnrctl services.
• Contents of the connection definition (hostname, port, service name, protocol).
• Wallet directory listing and mkstore -wrl <wallet_dir> -view output.
• Any relevant firewall or security group rules.

Verification

After each corrective action, return to SQL Developer, select the connection, and click Test. A successful test displays Status: Success. Additionally, you can run tnsping <service_name> from the client to confirm the listener resolves the service name; a successful ping returns an OK round‑trip time.

Limitations

• Ping may be blocked by ICMP firewalls; a successful ping is not required for TCP connectivity.
• Telnet may not be installed on minimal systems; use alternatives as noted.
• TNSPING only validates that the listener can be reached and the service name is resolvable; it does not authenticate the database.
• Modifying sqlnet.ora affects all Oracle clients on the machine; proceed only if you understand the impact.