Apinizer Oracle Connection – TNS and Time Zone Error Resolution

When creating an Oracle database connection, some environments may return a TNS resolution error, listener recognition issue, or a timezone-related failure. This usually occurs because the JDBC URL format does not match the Oracle server's actual connection information.

This page explains the correct DESCRIPTION-formatted JDBC URL structure and the oracle.jdbc.timezoneAsRegion=false parameter needed to configure the Oracle connection correctly in Apinizer.

1. TNS / Oracle Connection Error

If the Oracle connection setup returns an error such as the following:

• ORA-12154: TNS:could not resolve the connect identifier specified
• ORA-12514: TNS:listener does not currently know of service requested in connect descriptor
• ORA-12541: TNS:no listener
• Errors related to TNS or connect descriptor in the Oracle connection

It is recommended to define the JDBC URL in the DESCRIPTION format.

Required JDBC URL format

jdbc:oracle:thin:@(DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=<DB_IP_OR_HOST>)(PORT=<PORT>))(CONNECT_DATA=(SERVICE_NAME=<SERVICE_NAME>)))

Parameter explanation

Parameter	Description	Example
HOST	Oracle DB server IP address or hostname	192.168.1.10
PORT	Oracle listener port	1521
SERVICE_NAME	Oracle service name	ORCL

Example

If the Oracle database has:

• Host: 192.168.1.10
• Port: 1521
• Service Name: ORCL

Then use:

jdbc:oracle:thin:@(DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=192.168.1.10)(PORT=1521))(CONNECT_DATA=(SERVICE_NAME=ORCL)))

Note: SERVICE_NAME and SID are not the same thing. If your Oracle connection information is provided through SID, the JDBC URL format should be adjusted accordingly.

---

2. Time Zone Error

If the Oracle connection is established successfully but a Time Zone / timezone related error occurs during the connection, add the following parameter to the JDBC URL:

oracle.jdbc.timezoneAsRegion=false

Required JDBC URL format

jdbc:oracle:thin:@(DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=<DB_IP_OR_HOST>)(PORT=<PORT>))(CONNECT_DATA=(SERVICE_NAME=<SERVICE_NAME>)))?oracle.jdbc.timezoneAsRegion=false

Example

jdbc:oracle:thin:@(DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=192.168.1.10)(PORT=1521))(CONNECT_DATA=(SERVICE_NAME=ORCL)))?oracle.jdbc.timezoneAsRegion=false

This parameter helps prevent connection issues caused by the Oracle JDBC driver evaluating timezone information in region format.

---

3. Which JDBC URL Should Be Used in Which Case?

Situation	JDBC URL to Use
Standard Oracle connection	Oracle's standard JDBC URL format
TNS / connect descriptor error	DESCRIPTION formatted JDBC URL
Time Zone error	DESCRIPTION formatted URL + oracle.jdbc.timezoneAsRegion=false
Both TNS and Time Zone problems	DESCRIPTION formatted URL + oracle.jdbc.timezoneAsRegion=false

For TNS error

jdbc:oracle:thin:@(DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=<DB_IP_OR_HOST>)(PORT=<PORT>))(CONNECT_DATA=(SERVICE_NAME=<SERVICE_NAME>)))

For Time Zone error

jdbc:oracle:thin:@(DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=<DB_IP_OR_HOST>)(PORT=<PORT>))(CONNECT_DATA=(SERVICE_NAME=<SERVICE_NAME>)))?oracle.jdbc.timezoneAsRegion=false

---

4. Things to Check

When creating the JDBC URL, the following information should be verified with the Oracle administrator or the existing Oracle connection configuration:

1. HOST – Oracle DB server IP address or hostname
2. PORT – Oracle Listener port
3. SERVICE_NAME – Oracle service name
4. Oracle Listener accessibility on the relevant port
5. Network access from the server or pod running Apinizer to the Oracle DB

Especially in Kubernetes environments, connectivity should be checked from inside the Apinizer pod.

For example:

kubectl exec -it <apinizer-pod> -n <namespace> -- bash

Then check Oracle server reachability:

nc -vz <DB_IP_OR_HOST> <PORT>

For example:

nc -vz 192.168.1.10 1521

If the connection cannot be established, the issue may be related to network, firewall, security group, or Oracle Listener configuration, rather than the JDBC URL itself.

Summary

If an Oracle connection shows a TNS / connect descriptor error, use the DESCRIPTION-formatted JDBC URL.

If a Time Zone error appears, add the following parameter to the same URL:

?oracle.jdbc.timezoneAsRegion=false

Therefore, the most comprehensive format is:

jdbc:oracle:thin:@(DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=<DB_IP_OR_HOST>)(PORT=<PORT>))(CONNECT_DATA=(SERVICE_NAME=<SERVICE_NAME>)))?oracle.jdbc.timezoneAsRegion=false