Use Google Secret Manager secrets with Liquibase

Troubleshooting

Every message from this modifier begins with GCP Secret Manager. Most also name the fully qualified resource Liquibase tried to read. The messages below omit that prefix and show the resource as <resource>.

could not find <resource>. Verify the secret id, project, and version exist.

Cause: The secret, the project, or the requested version does not exist.

Resolution: Confirm the secret ID and project, and list the available versions with gcloud secrets versions list. Secret IDs are case-sensitive.

access denied for <resource>. Grant the authenticating identity roles/secretmanager.secretAccessor on this secret.

Cause: The identity authenticated successfully but cannot read the secret payload. The same message appears when the Secret Manager API is not enabled on the project, because Google returns the same permission-denied status for both.

Resolution: Read the Caused by: line printed below the message. If it reports that the Secret Manager API has not been used in the project or is disabled, enable the API and run the command again. Otherwise grant roles/secretmanager.secretAccessor as described in Step 1. If you granted it at the project level, check for a deny policy or an IAM condition that excludes this secret.

rejected the reference <resource> as malformed. Expected 'projects/<project>/secrets/<secret>/versions/<version>'.

Cause: Secret Manager rejected the resource name. Usually a mistyped resource name, but a shorthand secret ID that contains characters Secret Manager does not allow produces the same error after Liquibase expands it.

Resolution: Check for a missing or misspelled segment, such as 'secret/' instead of 'secrets/', or a stray slash. If you used the shorthand form, check the secret ID itself.

could not authenticate to read <resource>. Application Default Credentials are present but were rejected (expired or revoked). Re-run 'gcloud auth application-default login' or refresh the attached workload identity / service account. (cause: <exception>)

Cause: Credentials were found but Google Cloud rejected them.

Resolution: Follow the guidance in the message. If Liquibase runs with an attached workload identity or service account, confirm it is still enabled and its key is still valid.

could not obtain Google Application Default Credentials to read <resource>. Ensure ADC is configured: run 'gcloud auth application-default login', attach a workload identity or service account, or set GOOGLE_APPLICATION_CREDENTIALS to a service-account key file. (cause: <details>)

Cause: No credentials were found in the environment at all, which is different from credentials being rejected.

Resolution: Complete one of the three methods in Step 2. In a container, confirm the key file is mounted and that GOOGLE_APPLICATION_CREDENTIALS points at a path that exists inside the container.

could not determine a default GCP project for the shorthand secret '<secret>'. Set the project in your ADC/gcloud config, or use the full resource name 'gcp-secret-manager,projects/<project>/secrets/<secret>/versions/latest'.

Cause: You used the shorthand reference form but no default project is configured.

Resolution: Run gcloud config set project, export GOOGLE_CLOUD_PROJECT, or switch to a full resource name.

requires a secret reference: use 'gcp-secret-manager,<secret-id>' or 'gcp-secret-manager,projects/<project>/secrets/<secret>/versions/<version>'.

Cause: The prefix is present but nothing follows the comma.

Resolution: Add the secret reference after the comma.

returned an empty payload for <resource>.

Cause: The secret version resolved but contains no data.

Resolution: Liquibase treats an empty payload as an error rather than passing an empty value to the database. Add a new secret version with the intended value.

failed to resolve <resource>. (cause: ...)

Cause: Any other Secret Manager API error, with the underlying exception named in the cause.

Resolution: Check the cause, then confirm the Secret Manager API is enabled on the project and that you are within your read quota.

Requires the Liquibase GCP extension and a Liquibase Secure license

The extension is present but no valid Liquibase Secure license was found. The command fails rather than continuing with the reference unresolved. Add a valid Liquibase Secure license key to your configuration.

The property contains the keyword but the value is not resolved

Liquibase only resolves a value that begins with gcp-secret-manager,, including the comma. This warning usually means the comma is missing, or the prefix is not at the start of the value. Correct the reference format.

The reference is used literally as the password

If your database rejects the connection and the failure shows the full reference string as the attempted password, Liquibase never resolved the reference. This happens on Liquibase versions that do not include the GCP extension, where no warning is logged. Upgrade to Liquibase Secure 6.0 or later and confirm that liquibase --version lists the Liquibase GCP extension.