Oracle "ORA-12541: no listener": start it, or connect to the address it really uses

1. Is it running?

On the database server, as the oracle user, with its environment set:

lsnrctl status

If it says this, it just isn’t started:

TNS-12541: TNS:no listener
 TNS-12560: TNS:protocol adapter error
  TNS-00511: No listener

lsnrctl start

On Windows, it’s a service with a name like OracleOraDB19Home1TNSListener:

Get-Service *TNSListener*
Start-Service OracleOraDB19Home1TNSListener

After a reboot, it may not have started by itself, so set the service to automatic. On Linux, a systemd unit or dbstart usually handles it.

2. Did it start, and did it stay up?

Run lsnrctl status again, and read two things:

Listening Endpoints Summary...
  (DESCRIPTION=(ADDRESS=(PROTOCOL=tcp)(HOST=dbserver01)(PORT=1521)))
Services Summary...
Service "ORCLPDB1" has 1 instance(s).
  Instance "ORCL", status READY, has 1 handler(s) for this service...

The endpoint shows where it listens, and that has to match what the client uses. If it won’t start, the message usually says why:

3. Check listener.ora

It’s in $ORACLE_HOME/network/admin/:

LISTENER =
  (DESCRIPTION_LIST =
    (DESCRIPTION =
      (ADDRESS = (PROTOCOL = TCP)(HOST = 0.0.0.0)(PORT = 1521))
    )
  )

HOST is a usual suspect. If it’s localhost or 127.0.0.1, it only accepts local connections, and if it’s an old name or address after a server move, the listener can’t bind. Use the machine’s real name or address, or 0.0.0.0. Then restart:

lsnrctl stop
lsnrctl start

If the name isn’t in DNS, add it to /etc/hosts.

4. Is the client connecting to the right place?

Maybe the listener’s fine, and the client’s going somewhere else. Check its address:

tnsping MYDB

Attempting to contact (DESCRIPTION = (ADDRESS = (PROTOCOL = TCP)(HOST = 10.0.0.5)(PORT = 1521)) ...)
TNS-12541: TNS:no listener

Compare HOST and PORT with what the server’s listener shows. Non-default ports are often the cause: the alias in tnsnames.ora still says 1521 while the listener moved. An easy connect string takes tnsnames.ora out of the question:

sqlplus app@//10.0.0.5:1521/ORCLPDB1

Connecting to the wrong machine gives this too, particularly after a failover or a move. If the alias itself can’t be found, you’d get ORA-12154 instead.

5. Is it the network?

A firewall that rejects gives this error, and one that drops gives ORA-12170: TNS:Connect timeout occurred instead. Test from the client:

nc -vz 10.0.0.5 1521

Test-NetConnection 10.0.0.5 -Port 1521

On the server, open it only to the machines that need it:

sudo firewall-cmd --permanent --add-rich-rule='rule family="ipv4" source address="10.0.0.20" port port="1521" protocol="tcp" accept'
sudo firewall-cmd --reload

In the cloud, check the security group too. The Port Lookup has an entry for 1521: it shouldn’t be open to everyone. “Connection timed out” vs “Connection refused” explains the two failures.

6. Docker

Inside a container, localhost is that container, so use the service name. And to connect from your machine, the port has to be published:

docker run -d --name ora -p 127.0.0.1:1521:1521 -e ORACLE_PASSWORD=change-me gvenzl/oracle-free:23-slim
docker logs -f ora

Oracle takes a while to start, so wait for DATABASE IS READY TO USE!. Connecting before then gives this error, or ORA-12514. See connecting to localhost from a container.

7. It’s up, but the database isn’t registered

Now the listener answers, and you get the next error:

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

This is progress, as the listener works, and the service isn’t registered with it. The database registers itself within a minute of starting. To check and force it:

SHOW PARAMETER service_names;
SHOW PARAMETER local_listener;
ALTER SYSTEM REGISTER;

If the database is down, start it, and check lsnrctl status again. If local_listener has a wrong address or port, the database can’t find the listener, as with a non-default port.