- Error code
- ORA-12170
- Product
- Oracle Database
- Versions
- Oracle Database 19c, 21c, 23ai and 26ai (wording differs: see below)
- Category
- Connectivity & Listener
- Last reviewed
- 24 October 2026
On this page
What it means
ORA-12170 means a connection could not be completed in the time allowed: the client got no answer from the host and port (often a firewall silently dropping the traffic), or the server gave up on a client that was too slow to finish connecting.
Unlike ORA-12541, where the host answers at once that nothing is listening, ORA-12170 means nothing answered in time. On the client, the TCP connection is limited by TCP.CONNECT_TIMEOUT (60 seconds by default, applied to each IP address the host name resolves to), and the whole Oracle Net connection by SQLNET.OUTBOUND_CONNECT_TIMEOUT or a CONNECT_TIMEOUT in the connect string, which takes precedence. Oracle's reference names the usual reasons: network or system delays, a firewall that does not allow the connection, no network path between client and server, or a denial-of-service attempt on the server.
Current releases say which timer expired (for example TCP connect, outbound connect or receive), its value and the host and port, plus a CONNECTION_ID to find the attempt in trace files. 19c and 21c print only "TNS:Connect timeout occurred". The same code also appears on the server side: when a client does not finish connecting and authenticating within SQLNET.INBOUND_CONNECT_TIMEOUT, the server logs ORA-12170 with the client's address in its sqlnet.log, while the client receives ORA-12547 or ORA-12637.
Common causes
- A firewall, cloud security group or network security list between client and server drops traffic to the listener port.
- The connect string uses an address the client cannot reach, such as a private IP from outside the network, or the VPN that provides the route is down.
- The database host is down or unreachable, so nothing answers at all.
- The network or the server is slow and the configured timeouts (CONNECT_TIMEOUT, TCP.CONNECT_TIMEOUT, SQLNET.OUTBOUND_CONNECT_TIMEOUT) are too short for it.
- The host name resolves to several addresses (for example IPv6 and IPv4) that are unreachable, so the client waits for each one in turn.
- On the server side: clients that do not complete authentication within SQLNET.INBOUND_CONNECT_TIMEOUT, because of delays or a malicious client.
Diagnose it
Read-only These queries only read the data dictionary (USER_, ALL_ and DBA_ views) and dynamic performance views (V$). They do not change data, privileges or settings, so they are safe to run first. DBA_ and V$ views need the matching privileges.
Read which timeout expired
In current releases the message names the timeout type, its value and the host and port. A TCP connect timeout means the TCP handshake never completed (network or firewall). An outbound connect timeout includes the time to reach the instance. A receive timeout means the connection opened but the other side stopped answering. With a 19c or 21c client, enable client tracing or check the timeouts below to tell them apart.
Can the client reach the port at all?
Oracle's troubleshooting guide starts with basic connectivity from the client to the database server.
# Windows PowerShell
Test-NetConnection -ComputerName 203.0.113.25 -Port 1521
# Linux and macOS
nc -vz -w 10 203.0.113.25 1521
# Oracle tools: reach the listener for an alias
tnsping SALESDBA test that hangs and then fails confirms a network or firewall problem, not an Oracle one. If the port answers quickly but Oracle still times out, look at the Oracle Net timeouts and the server.
Check the client timeout settings
grep -i -E 'CONNECT_TIMEOUT|RECV_TIMEOUT' $TNS_ADMIN/sqlnet.ora $TNS_ADMIN/tnsnames.oraVery small values (for example a few milliseconds by mistake, since the units ms, sec and min are all accepted) make every connection time out. A CONNECT_TIMEOUT in the connect string overrides SQLNET.OUTBOUND_CONNECT_TIMEOUT.
On the server: which clients time out?
The server logs inbound timeouts with the client address in its sqlnet.log; Oracle's current reference also covers the error appearing in the database alert log. Querying the alert log through V$DIAG_ALERT_EXT needs a DBA account or SELECT_CATALOG_ROLE.
SELECT originating_timestamp, message_text
FROM v$diag_alert_ext
WHERE message_text LIKE '%12170%'
AND originating_timestamp > SYSTIMESTAMP - INTERVAL '1' DAY
ORDER BY originating_timestamp;Entries such as "Fatal NI connect error 12170" followed by a Client address: (ADDRESS=(PROTOCOL=tcp)(HOST=192.0.2.35)(PORT=52996)) line. Oracle warns that logged addresses can be forged.
How to fix it
Each fix is labelled with what it changes. Try read-only checks and the least invasive fix first, and test changes outside production.
Open the network path to the listener port
Changes configurationAllow TCP from the client addresses to the listener port (1521 by default) in every firewall on the way: the server's own firewall, network firewalls and cloud security groups or lists. On a managed cloud database the inbound rules live in the cloud console; see the Amazon RDS for Oracle page for an example.
Caution: Open the port only to the client addresses or networks that need it, never to the whole internet. Oracle's reference mentions disabling the firewall; a narrow rule is the safer way to the same result.
Use an address the client can reach
Client or network sideConnect to the public, VPN or private address that is actually routable from where the client runs, and check that the host name resolves to it.
sqlplus shop@//db.example.com:1521/salespdb.example.comAllow more time on a slow network
Client or network sideWhen the path works but is slow, raise the timeouts in the connect string (these take precedence) or in the client sqlnet.ora. Drivers have their own equivalents, for example oracle.net.CONNECT_TIMEOUT in JDBC or the TCP connect timeout in python-oracledb.
# Easy Connect with timeouts and retries
sqlplus shop@"db.example.com:1521/salespdb.example.com?connect_timeout=1min&transport_connect_timeout=30sec&retry_count=3"
# or in the client sqlnet.ora
SQLNET.OUTBOUND_CONNECT_TIMEOUT = 60
TCP.CONNECT_TIMEOUT = 30Server side: tune or protect the inbound timeout
Changes configurationIf legitimate clients on a slow network are logged with ORA-12170 on the server, raise SQLNET.INBOUND_CONNECT_TIMEOUT in the database's sqlnet.ora; Oracle recommends setting INBOUND_CONNECT_TIMEOUT_listener_name in listener.ora alongside it, to a lower value. If the source looks malicious, restrict access instead with TCP.VALIDNODE_CHECKING = YES and TCP.INVITED_NODES or TCP.EXCLUDED_NODES.
Caution: These timeouts protect the server from clients that open connections and never finish; do not set them very high or remove them. Valid node checking blocks every address not invited, so list all application servers first.
Examples
A firewall silently drops traffic to port 1521
Not reproduced here: no Oracle Database is installed for this site. The result shows the message format documented in Oracle's error reference for current releases (timeout type, timeout, host and port, connection ID); how the value and the address are printed and the CONNECTION_ID are illustrative. The wait matches the default TCP.CONNECT_TIMEOUT of 60 seconds documented in the Net Services Reference.
sqlplus shop@//203.0.113.25:1521/salespdb.example.com
-- waits about a minute, then:ORA-12170: Cannot connect. TCP connect timeout of 60s for host 203.0.113.25 port 1521. (CONNECTION_ID=Qm9vZ3VzQ29ubmVjdElEMw==)
An outbound connect timeout that is too short
Not reproduced here: no Oracle Database is installed for this site. Oracle's Net Services Reference states that a client that cannot establish the connection within SQLNET.OUTBOUND_CONNECT_TIMEOUT receives ORA-12170; the result is the 19c and 21c wording from the error reference. Ten milliseconds (the unit is easy to get wrong) is illustrative of a value too small for any real network.
# client sqlnet.ora
SQLNET.OUTBOUND_CONNECT_TIMEOUT = 10 ms
sqlplus shop@SALESDBORA-12170: TNS:Connect timeout occurred
How to prevent it
Document which networks may reach each database and keep the firewall and security-group rules for the listener port with that list, so new application servers are added before they go live. Test new environments with a port check and a real login from the actual client network, not from the database host.
Set connect timeouts deliberately: short enough that applications fail fast and can retry or fail over, long enough for the slowest legitimate network, and written with explicit units. Keep the server's inbound timeouts in place as protection.
Common questions
How do I fix ORA-12170 connect timeout?
Test whether the client can reach the host and listener port at all. If not, open the firewall or security group for that port from the client's address, or use a reachable address. If the port answers, check for timeouts that are too short in the connect string or sqlnet.ora.
Why ORA-12170 and not ORA-12541?
ORA-12541 comes back at once because the host refuses the connection: nothing listens on the port. ORA-12170 comes after a wait because nothing answers at all, which is typical of a firewall dropping packets, a wrong address or a host that is down.
I see ORA-12170 in the server logs but users report no errors. What is it?
The server logs ORA-12170 when a client does not finish connecting within SQLNET.INBOUND_CONNECT_TIMEOUT. The client sees ORA-12547 or ORA-12637 if it is still there. Check the logged client addresses: they may be health checks, slow clients or unwanted connection attempts.
Official documentation
- ORA-12170 (Oracle Database Error Messages)
- Parameters for the sqlnet.ora file (Net Services Reference 19c)
- Troubleshooting Oracle Net Services (Net Services Administrator's Guide 19c)
- Configuring naming methods: Easy Connect (Net Services Administrator's Guide 19c)
Last technically reviewed 24 October 2026; examples and diagnostics run on Oracle Database Error Messages reference (26ai, 21c and 19c); not run locally. Messages and explanations follow Oracle's Database Error Messages reference; no Oracle Database was available, so the examples were not run locally.