ansible/ansible · error · AnsibleVaultError

Did not find a match for --encrypt-vault-id=%s in the known

Error message

Did not find a match for --encrypt-vault-id=%s in the known vault-ids %s

What it means

Raised by match_encrypt_vault_id_secret() in lib/ansible/parsing/vault/__init__.py when encrypting with an explicit --encrypt-vault-id that matches none of the loaded vault identities. Unlike the best-secret path, it deliberately refuses to fall back to the first/other available secret, because the user explicitly named the identity to encrypt with. The message lists the known vault-ids for diagnosis.

Source

Thrown at lib/ansible/parsing/vault/__init__.py:559


def match_encrypt_vault_id_secret(secrets, encrypt_vault_id=None):
    # See if the --encrypt-vault-id matches a vault-id
    display.vvvv(u'encrypt_vault_id=%s' % to_text(encrypt_vault_id))

    if encrypt_vault_id is None:
        raise AnsibleError('match_encrypt_vault_id_secret requires a non None encrypt_vault_id')

    encrypt_vault_id_matchers = [encrypt_vault_id]
    encrypt_secret = match_best_secret(secrets, encrypt_vault_id_matchers)

    # return the best match for --encrypt-vault-id
    if encrypt_secret:
        return encrypt_secret

    # If we specified a encrypt_vault_id and we couldn't find it, dont
    # fallback to using the first/best secret
    raise AnsibleVaultError('Did not find a match for --encrypt-vault-id=%s in the known vault-ids %s' % (encrypt_vault_id,
                                                                                                          [_v for _v, _vs in secrets]))


def match_encrypt_secret(secrets, encrypt_vault_id=None):
    """Find the best/first/only secret in secrets to use for encrypting"""

    display.vvvv(u'encrypt_vault_id=%s' % to_text(encrypt_vault_id))
    # See if the --encrypt-vault-id matches a vault-id
    if encrypt_vault_id:
        return match_encrypt_vault_id_secret(secrets,
                                             encrypt_vault_id=encrypt_vault_id)

    # Find the best/first secret from secrets since we didn't specify otherwise
    # ie, consider all the available secrets as matches
    _vault_id_matchers = [_vault_id for _vault_id, dummy in secrets]
    best_secret = match_best_secret(secrets, _vault_id_matchers)

    # can be empty list sans any tuple

View on GitHub (pinned to 9cf16a4aca)

Solutions

List the ids you actually loaded and correct the --encrypt-vault-id value to one of them (the error message prints the known ids).
Ensure a secret source for that id is provided: --vault-id prod@prod-pass.txt so 'prod' is registered before encrypting.
If the id source failed to load (missing file, script error), fix that first — the id is absent because its secret never loaded.
Or drop --encrypt-vault-id to use the default best-secret selection.

Example fix

# before
ansible-vault encrypt secret.yml --encrypt-vault-id prod   # only 'default' loaded
# after
ansible-vault encrypt secret.yml --encrypt-vault-id prod --vault-id prod@prod-pass.txt

Defensive patterns

Strategy: validation

Validate before calling

known_ids = {v for v, _vs in secrets}  # same shape as match_* helpers
if encrypt_vault_id not in known_ids:
    raise ValueError(f'--encrypt-vault-id {encrypt_vault_id!r} not loaded; known ids: {sorted(known_ids)}')
from ansible.parsing.vault import match_encrypt_vault_id_secret
secret = match_encrypt_vault_id_secret(secrets, encrypt_vault_id)

Try / catch

from ansible.parsing.vault import AnsibleVaultError
try:
    secret = match_encrypt_vault_id_secret(secrets, encrypt_vault_id='prod')
except AnsibleVaultError as e:
    raise ConfigError('load a secret source for vault-id prod (e.g. --vault-id prod@file) before encrypting') from e

Prevention

Always pair --encrypt-vault-id NAME with a loaded --vault-id NAME@source.
Centralize vault-id labels in one env config to prevent typo drift between environments.
Fail fast in CI: assert the requested encrypt id is present in the loaded secret list before running ansible-vault.

When it happens

Trigger: Running ansible-vault encrypt --encrypt-vault-id prod ... when the only loaded secrets have ids like 'default' or 'staging'; a typo in the id; the @source for that id failing to load so it never registers; using match_encrypt_vault_id_secret() programmatically with a secrets mapping lacking the id.

Common situations: CI pipelines parameterized with a vault-id label that differs from the provisioned one; renaming identities without updating pipelines; the password source for the named id silently failing earlier (bad file path) so the id never enters the secrets list.

Related errors

AI-assisted analysis of ansible/ansible@9cf16a4aca (2026-08-15). Data as JSON: /api/errors/60d41a917e8c193e. Report an issue: GitHub.