How to Fix ORA-12170: TNS:Connect Timeout Occurred

ORA-12170 means Oracle could not complete connection establishment or network communication before a timeout expired. Fix it by identifying the connection phase that timed out, checking the database endpoint from the failing application environment, and adjusting the relevant timeout only when the connection is genuinely slow. Increasing a timeout will not repair an incorrect hostname, a blocked port, or an unavailable listener.

Use the symptom to choose your first check:

Symptom Likely Cause First Check or Fix
Connections fail after a network, VPN, or firewall change Traffic cannot reach the database endpoint Test the destination port from the affected client
Only one application, container, or host fails Different DNS, routing, credentials configuration, or connection settings Inspect that runtime’s effective connection configuration
The TCP port is reachable, but Oracle login times out Connection handoff, authentication, or server-side delay Correlate client, listener, and database logs
Editing a timeout has no effect A connection-string override, driver setting, or inactive configuration file Identify which setting the application actually loads
Applications work, but the database alert log contains timeouts A different client is leaving connections incomplete Match timestamps and source addresses before changing limits

What ORA-12170 Means

Oracle connections involve more than opening a network socket. The client resolves the destination, establishes transport connectivity, contacts an Oracle listener, and completes the work needed to establish a database session. A timeout can occur at different points in that process.

Common causes include:

  • An incorrect hostname, port, or connection descriptor.
  • A firewall, cloud network rule, VPN, or route blocking traffic.
  • A listener that is unavailable or listening on a different interface.
  • Slow authentication, server resource pressure, or network delays.
  • A timeout that is too short for an otherwise healthy connection.
  • Incomplete or potentially malicious connection attempts reaching the server.

The error alone does not establish which cause applies. It also does not prove that the database instance has shut down.

Older clients may show only ORA-12170: TNS:Connect timeout occurred. Newer messages can include the timeout category, destination, elapsed limit, and a connection identifier. Those details are more useful than the error number alone.

How to Fix ORA-12170

ORA-12170 can result from transport connectivity, listener handoff, authentication, or database responsiveness failures, depending on the timeout phase.

Step 1: Capture the Full Error and Identify the Phase

  1. Copy the complete error, including any nested driver exception. Record the timestamp and time zone, affected application, client version, and destination.
  2. Read the timeout category before editing configuration. For Oracle Database, TCP identifies transport connection establishment, OUTBOUND_CONNECT identifies the overall outbound connection-establishment phase, and RECEIVE identifies a wait for incoming data, according to Oracle’s ORA-12170 error reference.
  3. Establish where the error appeared: the application, a client log, or the database alert log. Save the CONNECTION_ID if the message includes one; it can connect the failure to entries in trace files.

A transport timeout calls for endpoint and network checks first. A timeout later in connection establishment needs more attention to listener handoff, authentication, and database responsiveness.

If the message does not identify a phase, continue with connectivity tests rather than guessing which timeout expired.

Step 2: Verify the Connection Details Actually in Use

  1. Inspect the failing process’s effective connection configuration, not just the file you expect it to use. Check the hostname, listener port, service name, and whether the application uses Easy Connect, a TNS alias, or a driver-built descriptor.
  2. If the client uses Oracle Net configuration files, check its TNS_ADMIN setting and active Oracle home. Multiple client installations, service accounts, and container images can load different copies of tnsnames.ora and sqlnet.ora.
  3. Resolve the database hostname from the affected runtime.

On Windows PowerShell:

Resolve-DnsName db.example.com

On Linux systems with getent:

getent ahosts db.example.com

Replace db.example.com and the sample ports in subsequent commands with the actual destination.

Compare the returned addresses with the intended database endpoint. If the hostname resolves differently on working and failing clients, correct the relevant DNS or runtime configuration and repeat the connection attempt.

Do not permanently substitute an IP address without checking the deployment. Clustered endpoints, failover configurations, and certificate validation may depend on the configured hostname.

Step 3: Test the Listener Port From the Failing Runtime

  1. Run the port test from the application host, container, or pod where the error occurs. Success from an administrator’s laptop does not establish that the application has the same route.
  2. Test the exact port in the application’s connection descriptor.

On Windows PowerShell:

Test-NetConnection -ComputerName db.example.com -Port 1521

On Linux with OpenBSD-compatible netcat:

nc -vz db.example.com 1521
  1. Interpret the port-test results as follows: – Timeout: Check routing, VPN connectivity, network policies, cloud security rules, and host firewalls. A timeout can also result from an unreachable host. – Connection refused: Something actively rejected the connection. Check whether the listener is running and whether the configured address and port are correct. – Successful connection: Transport connectivity works to that endpoint. Continue investigating the Oracle connection process.

If traffic is blocked, allow only the required application sources and database destination through the relevant controls. Do not leave a firewall disabled as a workaround.

After changing a route or rule, repeat the port test and attempt a fresh Oracle login. If the port is still unreachable, increasing an Oracle timeout only makes the failure take longer.

Step 4: Check the Listener and Correlate Logs

A successful port test proves transport reachability, not a working Oracle session.

  1. Ask the DBA to run lsnrctl status on the database host to verify the listener. Replace LISTENER_NAME with the configured listener name.
lsnrctl status LISTENER_NAME

Check that the listening endpoints match the intended protocol, interface, and port.

  1. Use lsnrctl services to check whether the listener knows the required database service:
lsnrctl services LISTENER_NAME

A running listener does not guarantee that the requested service is available. Conversely, an incorrect service name often produces a different Oracle error, so do not assume every connection failure is a timeout problem.

If an independently managed listener is stopped and you are authorized to start it:

lsnrctl start LISTENER_NAME

For a listener managed by Oracle Grid Infrastructure or another service manager, restore it through that manager rather than starting a competing process manually. Confirm its endpoints and service registration afterward.

  1. Correlate the failed connection attempt with entries in the listener log, database alert log, and available client traces. Use the timestamp, source information, and CONNECTION_ID where available.

Look for delays during authentication, connection handoff, or server resource allocation. If the initial listener redirects the client to another endpoint, that destination must also be reachable.

The absence of a matching listener-log entry is useful evidence, but not proof that traffic never arrived: logging configuration and connection failure timing affect what is recorded.

Step 5: Adjust Only the Timeout That Governs the Failure

Do this after confirming the destination is reachable and finding evidence that legitimate connection activity needs more time. There is no universal timeout value that fixes ORA-12170.

  1. Check the connection string first. For Oracle Database connections using Easy Connect or tnsnames.ora, increase CONNECT_TIMEOUT for overall connection establishment or TRANSPORT_CONNECT_TIMEOUT for the transport connection, as appropriate. Oracle connection-string parameters take precedence over their corresponding sqlnet.ora parameters. Editing the file will not override a shorter value already embedded in the connection descriptor.
  2. For an application using Oracle Net client configuration, edit the client file. Oracle Database’s applicable client-side controls are SQLNET.OUTBOUND_CONNECT_TIMEOUT for outbound connection establishment, TCP.CONNECT_TIMEOUT for transport establishment, and SQLNET.RECV_TIMEOUT for waiting to receive data. Change the matching parameter in the client’s active sqlnet.ora, not automatically in the database server’s file.
  3. For JDBC, check the driver configuration. Oracle JDBC provides oracle.net.OUTBOUND_CONNECT_TIMEOUT and oracle.net.CONNECT_TIMEOUT; setLoginTimeout() can control login timing where supported by the connection API. Bare numeric values for those JDBC properties are in milliseconds, while setLoginTimeout() takes seconds. Do not copy an Oracle Net numeric value directly into a JDBC property without converting its unit. Also inspect connection-pool settings that can impose a separate deadline.
  4. For Python, use the actual driver keyword. For Oracle’s python-oracledb driver, the TCP connection control, called TcpConnectTimeout in the Oracle error reference, is exposed through the Python keyword tcp_connect_timeout, measured in seconds, when calling connect() or create_pool(). Use the Python keyword rather than passing TcpConnectTimeout as a Python argument. Do not assume that changing sqlnet.ora affects every driver or connection mode.
  5. Keep the original value and change one relevant control at a time. Choose a limit that accommodates measured normal connection time without exceeding the application’s acceptable startup or request deadline.

A longer timeout is appropriate for legitimate latency. It is not a substitute for correcting persistent server overload or unreachable endpoints.

Step 6: Test a New Database Session

  1. Make the application load the updated configuration. Depending on the runtime, this may require recycling its connection pool or restarting the affected process. Reusing an established session does not test connection establishment.
  2. Attempt a new connection using the application’s actual driver and connection configuration. If SQL*Plus uses the same intended TNS alias, it can provide a separate diagnostic check:
sqlplus app_user@MYDB

Replace the username and alias. Enter the password at the prompt rather than embedding it in the command.

  1. After a fresh login, use SYS_CONTEXT to confirm the session’s database service:
SELECT SYS_CONTEXT('USERENV', 'SERVICE_NAME') FROM dual;

Then repeat the operation through the application itself. A successful SQL*Plus login does not prove that a JDBC or Python process loads the same configuration.

Confirm that new connections complete and that no matching timeout appears in the logs. If a timeout change produces no improvement, restore the previous value unless there is a separate documented reason to retain it.

When ORA-12170 Appears in the Database Alert Log

A server-side log entry needs a server-side investigation. It may describe an incomplete connection from another client, even when your application is working.

  1. Correlate the alert-log entry with an application attempt and available network or listener records. If it does not match the affected application, identify the actual source before changing application settings.
  2. Check database-host resource pressure and authentication delays. Address those causes before relaxing connection protections.
  3. If legitimate clients need more time, Oracle Database’s alert-log remedy is to increase SQLNET.INBOUND_CONNECT_TIMEOUT, which governs incoming connection establishment, or SQLNET.RECV_TIMEOUT in the database’s sqlnet.ora.

For the older TNS:Connect timeout occurred message caused by a slow network or system, Oracle Database also provides SQLNET.SEND_TIMEOUT for sending data, alongside the inbound and receive controls. These server-side timeout values use seconds; increase only the control associated with the observed delay.

Do not lengthen limits merely to accommodate unexplained incomplete connections. If malicious clients are suspected, correlate the source address in the alert log or sqlnet.log with firewall and network records. Logged TCP/IP addresses can be forged, so they are not definitive identification on their own.

Restrict confirmed unwanted sources through scoped access controls. After either a configuration or access-control change, open a new session from an authorized client and confirm that legitimate connections work and the unwanted timeout pattern stops.

When Only One Application or Container Fails

Containers and Kubernetes Pods

A container has its own network context. A hostname that works on the host may resolve differently inside the workload, and localhost normally refers to that container or pod rather than a database running elsewhere.

Check the workload’s actual environment variables, mounted Oracle configuration files, DNS results, and destination port. For Kubernetes, inspect applicable egress and ingress NetworkPolicies as well as external network controls.

If a database hostname returns several addresses, compare those addresses with the failing attempts. One unreachable destination can produce intermittent failures while other connections succeed.

Correct the workload’s endpoint or narrowly scoped network rule, deploy the updated configuration, and test a newly established database session from that workload. Confirm the expected service with a query before treating the issue as resolved.

Connection Pools and Intermittent Failures

Separate a timeout while creating a physical database connection from a timeout while waiting for an available pooled connection. They have different causes and may use different settings.

Inspect the underlying driver exception rather than only the pool’s wrapper message. Determine whether the pool is opening new connections, checking existing sessions, or waiting because every connection is already in use.

Compare failing timestamps with deployment events, connection bursts, database load, and network changes. If a pool configuration change is justified, apply it through the application’s normal configuration mechanism and recycle the pool in a controlled way.

Verify both a fresh connection and the application operation that originally failed. Do not use unlimited retries to hide a failing connection path; retries can add load while delaying the same error.

Confirm the Fix and Prevent Repeat Timeouts

A complete fix should pass these checks:

  • The affected runtime resolves the intended database destination.
  • New database sessions establish successfully through the application’s own driver.
  • The application reaches the expected database service.
  • Logs contain no matching timeout for the successful test.
  • Temporary diagnostic changes have been removed.
  • Network access remains restricted to the required sources and destinations.

Keep timeout configuration in an identifiable place and record its unit. When applications have multiple connection layers, document which layer controls transport establishment, overall login, and pool waiting.

Monitor connection-establishment time separately from query execution time. A slow login and a slow SQL statement are different problems, even if both eventually surface as an application timeout.

If new connections still fail, send the DBA or network team a redacted connection descriptor, timestamp and time zone, client and driver versions, source and destination details, port-test results, and the connection identifier. That evidence gives them a specific failed attempt to investigate.

Frequently Asked Questions

Does ORA-12170 Need a Different Fix in Oracle 19c?

No. Oracle 19c troubleshooting still starts with the effective connection destination, network reachability, listener availability, and the relevant client or server timeout. The displayed message may contain fewer diagnostic details, making correlated logs more important.

What Does “TCP Connect Timeout of 20s” Mean?

“TCP Connect Timeout of 20s” means the client did not establish a TCP connection to the listed host and port within 20 seconds. That is the limit reported for that attempt, not a universal Oracle timeout default. A longer limit can accommodate legitimate delay, but it will not make a blocked or incorrect endpoint reachable.

Is ORA-12170 a SQL Server Connection Timeout?

No, ORA-12170 is an Oracle error, not a native Microsoft SQL Server error. Oracle SQL Developer is also a client application, not Microsoft SQL Server. If a SQL Server workflow displays ORA-12170 while accessing Oracle through an external connection, investigate that Oracle connection; for a native SQL Server timeout, use the SQL Server driver’s actual error message.

How do you configure an Oracle connection timeout?

Configure the timeout in the settings used by the client that opens the Oracle connection. For an Easy Connect string or a tnsnames.ora descriptor, use CONNECT_TIMEOUT or TRANSPORT_CONNECT_TIMEOUT; a value in that descriptor overrides the corresponding sqlnet.ora value. For Oracle Net client configuration, adjust SQLNET.OUTBOUND_CONNECT_TIMEOUT, SQLNET.RECV_TIMEOUT, or TCP.CONNECT_TIMEOUT in the client sqlnet.ora file.