SQLPlus Fails with ORA-01017 When Using runWith: sqlplus Despite Successful JDBC Connection

Applies to

• Liquibase Secure (Pro)

Conditions

• Oracle database connections

• Liquibase configured to use runWith: sqlplus in changesets

(Optional): Some troubleshooting steps in this article reference Docker. These apply only if Liquibase and SQLPlus are being run inside a Docker container.

Issue Summary

When using runWith:sqlplus in a changeset, JDBC connections to the database may succeed, but SQLPlus can fail with the error ORA-01017: invalid username/password; logon denied.

Although the error suggests a credential mismatch, the underlying cause can be related to the JDBC URL format. JDBC may allow a username embedded in the URL, but this results in an invalid SQLPlus connection string when Liquibase translates it.

Error Message

ORA-01017: invalid username/password; logon denied

Potential Root Causes

To troubleshoot this issue, verify the following in order:

1. Database connectivity – Confirm SQLPlus can connect directly to the database.

2. Password formatting – Ensure there are no unsupported special characters (such as @ or &) or trailing spaces in the password.

3. Configuration sources – Check that credentials are consistently passed (for example, using environment variables or via liquibase.properties or liquibase.sqplus.conf config files).

4. Unnecessary files – Confirm that extra Oracle configuration files (like sqlnet.ora) are not interfering with username/password authentication.

5. JDBC URL format – Ensure the JDBC URL does not include the username before the host. Even though JDBC will allow username in the URL, SQLPlus does not. 

Troubleshooting

Step 1: Test SQLPlus Connectivity

Run SQLPlus directly to confirm basic connectivity:

sqlplus USERNAME/PASSWORD@hostname:port/SERVICE_NAME

(Optional for Docker users): If you are running Liquibase inside Docker, test connectivity from within the container:

sudo docker run -it \
   --rm \
   liquibase-with-sqlplus:1.0 \
   sh -c "sqlplus USERNAME/PASSWORD@hostname:port/SERVICE_NAME"

Step 2: Validate Password Formatting

• Echo the password in clear text to confirm no characters are altered by the shell or CI/CD tool.

• Review Password Character Requirements.

• Ensure no accidental spaces are present before or after the password.

Step 3: Check Credential Sources

• Use environment variables to provide credentials:

  • LIQUIBASE_COMMAND_USERNAME

  • LIQUIBASE_COMMAND_PASSWORD

• If using liquibase.sqlplus.conf, ensure that username and password are correct:

  • liquibase.sqlplus.username=<username>
  • liquibase.sqlplus.password=<password>

Step 4: Remove Unnecessary Oracle Config Files

• If a sqlnet.ora file exists (or referenced through the TNS_ADMIN variable) remove this file as it is not needed for Oracle authentication using username/password. 

Step 5: Verify JDBC URL Format

Check the JDBC URL being used in Liquibase.

❌ Incorrect (includes username in the URL):

jdbc:oracle:thin:username/@hostname:port/database

✅ Correct (username is provided separately via Liquibase credentials, not in the URL):

jdbc:oracle:thin:@hostname:port/database

Liquibase passes the username/password to SQLPlus separately. If the username is embedded in the URL, the generated SQLPlus connection string becomes invalid and produces ORA-01017.

Related Article(s)

• Liquibase Documentation: runWith attribute