Oracle ORA-12514 Resolution Guide: Causes and Solutions for Listener Connection Errors

The error “ORA-12514: TNS:listener does not currently know of service requested in connect descriptor” occurs when the listener does not recognize the Service Name (SERVICE_NAME) specified by the client during an Oracle Database connection attempt. This article provides a comprehensive overview of the causes of this error, along with specific procedures and checkpoints for resolution.

Conclusion & Shortest Path to Resolution for ORA-12514
What is ORA-12514? Background and Fundamentals
1. Definition from Official Documentation
2. Note for Beginners: Service Names and Domains
Common Scenarios Where ORA-12514 Occurs (Case Studies)
Procedures & Implementation: Isolation and Fixes
Troubleshooting: Comparison with Common ORA-Errors
Operational & Monitoring Considerations
FAQ (Frequently Asked Questions)
Summary

Conclusion & Shortest Path to Resolution for ORA-12514

When ORA-12514 occurs, please verify the following steps in order:

Verify with Easy Connect (EZConnect): To isolate issues within tnsnames.ora, attempt to connect by directly specifying the hostname and service name.
Check Listener Status: Run lsnrctl status or lsnrctl services on the server side to confirm if the service is registered.
Verify Exact Match of Service Name: If a domain name is involved, ensure it is described accurately, including the domain suffix.
Check Instance/PDB Status: Confirm that the database and Pluggable Database (PDB) are in the OPEN state.

What is ORA-12514? Background and Fundamentals

ORA-12514 is an error returned when the listener—the “gateway” for network communication—cannot find the requested Service Name (SERVICE_NAME) in its management list.

[oracle@v19single ~]$ sqlplus system/oracle@V19_CONNECTION

SQL*Plus: Release 19.0.0.0.0 - Production on Sun Apr 5 00:00:57 2026
Version 19.21.0.0.0

Copyright (c) 1982, 2022, Oracle.  All rights reserved.

ERROR:
ORA-12514: TNS:listener does not currently know of service requested in connect
descriptor

KW1: ORA-12514 (Error displayed on the client side)
KW2: TNS-12514 (Identification number output in the listener log listener.log)

Definition from Official Documentation

Cause: The listener received a request to establish a connection to a database or other service. The connect descriptor received by the listener specified a name of a service (usually a database service) that was either not dynamically registered with the listener or has not been statically configured for the listener. This may be a temporary condition such as after the listener has started, but before the database instance has registered with the listener.

Note for Beginners: Service Names and Domains

In environments running 19c and later, it is common for Service Names to include a DB Domain (e.g., .example.com). Since the listener identifies services by their “Fully Qualified Service Name,” ORA-12514 will occur if there is a mismatch regarding the domain suffix.

Common Scenarios Where ORA-12514 Occurs (Case Studies)

Below are representative cases encountered in practical operations.

1. Service Name Mismatch in tnsnames.ora

The most frequent cause is a typo in SERVICE_NAME = v19 or omitting the domain name (e.g., v19.example.com).

Note that the tnsnames.ora file is stored by default under the $ORACLE_HOME/network/admin directory.

2. PDB (Pluggable Database) is Closed

In a multitenant architecture, if a PDB remains in the MOUNTED state, the services specific to that PDB will not be published to the listener.

3. Dynamic Registration Lag (Up to 60 Seconds)

Immediately after a database starts, it takes several dozen seconds for the background process (LREG) to notify the listener. Connecting during this “registration wait” period results in an error.

To ensure reliable dynamic registration, it is recommended to follow the “Listener Start → DB Start” sequence (ideally, the listener should be ready when the DB starts).

4. Listener Port Number Mismatch

If the listener is listening on a port other than the default 1521, and the LOCAL_LISTENER parameter is not set on the DB side, the DB will not know where the listener is and cannot register its services.

Procedures & Implementation: Isolation and Fixes

Step 1: Isolate the Cause with Easy Connect (EZConnect)

To determine whether the issue lies with tnsnames.ora settings or the DB side, attempt a connection using the following format:

# Format: sqlplus username/password@hostname:port/service_name
sqlplus system/password@v19single:1521/v19

Notes:

If the hostname “v19single” cannot be resolved, specify the IP address directly.

Important: If the service name includes a domain (e.g., v19.jp.oracle.com), you must enter the full name including the domain.

If this connects: There is an error in the tnsnames.ora content (SERVICE_NAME or parenthesis structure).
If this still results in ORA-12514: The listener does not recognize the service v19.

Step 2: Actions Based on Official Documentation

Perform the following checks to resolve the error:

Wait a Moment: If the database was just started, wait and try connecting again until registration completes.
Check Listener Services: Execute lsnrctl services <listener_name> to see which services are currently running.
Re-verify Parameters: Ensure the SERVICE_NAME parameter matches the service recognized by the listener.
Check Logs: Examine the events in the listener.log file to investigate the history of rejected connections.

Execution Example: Correct Connection Settings

Example of tnsnames.ora using hostname v19single and service name v19.

# Example of tnsnames.ora
# Default location: $ORACLE_HOME/network/admin/tnsnames.ora
V19_CONNECTION =
  (DESCRIPTION =
    (ADDRESS = (PROTOCOL = TCP)(HOST = v19single)(PORT = 1521))
    (CONNECT_DATA =
      (SERVER = DEDICATED)
      (SERVICE_NAME = v19) # If a domain exists, write the full name like v19.example.com
    )
  )

Supplemental Note: The most reliable method is to copy the value output by SQL> show parameter service_names exactly as it appears.

Troubleshooting: Comparison with Common ORA-Errors

Error Code	Cause	Action
ORA-12514	Listener responded, but the service name is not in the list.	Check with EZConnect, verify domain name.
ORA-12541	Listener is not started.	Run `lsnrctl start` on the server.
ORA-12154	Connection identifier not found in `tnsnames.ora`.	Check TNS name spelling, verify file location.

Operational & Monitoring Considerations

Adhere to Startup Sequence: If the DB was started first, you can force immediate registration using the ALTER SYSTEM REGISTER; command.
Automatic Domain Suffix: If NAMES.DEFAULT_DOMAIN is set in sqlnet.ora, a domain might be unintentionally appended to the service name, causing a mismatch.
PDB Auto-start: To ensure a PDB opens automatically when the CDB restarts, execute ALTER PLUGGABLE DATABASE v19 SAVE STATE;.

FAQ (Frequently Asked Questions)

Q1: How can I check if a service name has a domain? A1: Check SHOW PARAMETER DB_DOMAIN within the DB, or check the full service name displayed in the lsnrctl status output.

Q2: Easy Connect works, but TNS connection fails. A2: It is highly likely that the SERVICE_NAME in tnsnames.ora is missing the domain or has a typo. Copy the exact string used in the successful Easy Connect attempt into your configuration.

Q3: What if I want to use a port other than 1521? A3: You must not only change the PORT in tnsnames.ora but also configure the LOCAL_LISTENER parameter on the DB side to inform the database of the listener’s location.

Summary

ORA-12514 indicates the listener does not recognize the service name requested by the client.
The shortcut to resolution is using Easy Connect (EZConnect) to isolate configuration file issues.
If the service name has a domain, always include the domain name in the description.
Develop the habit of starting the “Listener first, then the DB” to prevent startup issues.

This article is based on Oracle Database 19c (screens and default values may differ for other versions).