Oracle "ORA-12514: listener does not currently know of service": check the name, then the registration

1. What does the listener know?

lsnrctl status

Services Summary...
Service "FREE" has 1 instance(s).
  Instance "FREE", status READY, has 1 handler(s) for this service...
Service "freepdb1" has 1 instance(s).
  Instance "FREE", status READY, has 1 handler(s) for this service...
The command completed successfully

lsnrctl services gives more detail. Now compare with what you asked for, in your connection string or tnsnames.ora. Names aren’t case-sensitive, and typos and old names are common: a PDB renamed, or a connection string copied from another environment.

2. Service name, not SID

Two different things are often mixed up. Easy Connect, host:port/NAME, always means a service name. In tnsnames.ora, check which one the entry uses:

SHOP =
  (DESCRIPTION =
    (ADDRESS = (PROTOCOL = TCP)(HOST = 10.0.0.5)(PORT = 1521))
    (CONNECT_DATA = (SERVICE_NAME = shop))
  )

SID = ORCL in place of SERVICE_NAME asks for an instance by its old-style name. Since Oracle 12c, a pluggable database (PDB) can only be reached by its service name, so a SID entry for it fails. Use SERVICE_NAME. To see the right names from inside the database:

SELECT name, network_name FROM v$services;
SHOW PARAMETER service_names;

3. The database, or the PDB, isn’t open

A database that’s down, or still starting, hasn’t registered its services. A PDB that’s closed is listed, and can’t accept connections. Check, as SYSDBA:

SELECT instance_name, status FROM v$instance;
SELECT name, open_mode FROM v$pdbs;

Open a PDB, and make it open again after restarts:

ALTER PLUGGABLE DATABASE shop OPEN;
ALTER PLUGGABLE DATABASE shop SAVE STATE;

Without SAVE STATE, PDBs come up closed after each restart, and this error returns every time the server reboots.

4. Registration

The database registers itself with the listener, every minute or so. Right after the listener or the database starts, there’s a short window when the service isn’t known yet. Force it:

ALTER SYSTEM REGISTER;

If registration never happens, the database is probably looking for the listener in the wrong place. That’s typical with a listener on a port other than 1521, or on another address:

SHOW PARAMETER local_listener;
ALTER SYSTEM SET local_listener = '(ADDRESS=(PROTOCOL=TCP)(HOST=10.0.0.5)(PORT=1522))';
ALTER SYSTEM REGISTER;

Then lsnrctl status should show your services within seconds.

5. Static registration

Some tasks connect while the database is down, such as starting it remotely, or RMAN duplication. Those need the service written into listener.ora, because a stopped database can’t register:

SID_LIST_LISTENER =
  (SID_LIST =
    (SID_DESC =
      (GLOBAL_DBNAME = shop)
      (ORACLE_HOME = /opt/oracle/product/19c/dbhome_1)
      (SID_NAME = ORCL)
    )
  )

Then lsnrctl reload. Such entries show with the status UNKNOWN, which is normal for them.

6. Docker

With gvenzl/oracle-free, the default PDB is FREEPDB1, and ORACLE_DATABASE adds another. Connect from the host with the published port:

sqlplus app/password@//localhost:1521/FREEPDB1

Right after the container starts, wait for DATABASE IS READY TO USE! in docker logs. Before that, you get this error, as the services aren’t registered yet.