Troubleshooting Scenario Questions

Vault is not configured to use SSL/TLS for LDAP

Why it fails: The bind error reports invalid credentials, so the failure occurs during authentication, not transport; missing SSL/TLS would surface as a connection or handshake error instead. Enabling LDAPS is the right step when the directory rejects plaintext binds or the environment mandates encrypted LDAP traffic.

The LDAP server does not allow anonymous binds

Why it fails: Vault performs the bind using the configured bind DN and password, so anonymous-bind restrictions do not produce an invalid-credentials error. Allowing anonymous binds matters when Vault is deliberately configured to search the directory without service-account credentials.

The LDAP server certificate is not trusted by Vault

Why it fails: An untrusted certificate causes TLS verification errors, not 'invalid credentials' bind failures. That message means the bind DN or password Vault uses is wrong, or the account is locked. Certificate trust would be the cause if Vault reported x509 verification failures instead.

The token is not a root token

Why it fails: Root status is irrelevant: non-root tokens routinely write when policy permits. The real failure is that KV v2 paths are prefixed with 'data/', so 'secret/team-alpha/*' never matches 'secret/data/team-alpha/db-creds'. Root tokens are only needed for privileged operations such as mounting engines or managing auth methods.

The token's TTL has expired

Why it fails: An expired TTL produces a token-expired error on every request, not a selective denial of one path. The policy itself would still match if the token were valid. TTL expiry is the correct diagnosis when a token previously worked and now fails everywhere, which is not the pattern described here.

The token has a conflicting policy from a parent token

Why it fails: Vault policies are additive, so a parent token's policies cannot remove or conflict with a child's grants; the union applies. The denial stems from the KV v2 'data/' path prefix, which the wildcard policy omits. Conflicting policies are relevant when designing least-privilege boundaries, not when explaining a single denied write.

Run 'vault write' to test if the token can write to a path.

Why it fails: 'vault write' mutates data, so using it as a diagnostic risks creating or overwriting secrets at the target path. It is tempting because a write does confirm token policy permissions, and it is the correct test when validating that a token can legitimately create a specific secret.

Run 'vault status' to check if the server is reachable.

Why it fails: 'vault status' reports seal state and cluster health but returns successfully even when the caller's token is invalid or lacks policy permissions, so it cannot explain authorisation failures. It is the right first step when the server itself may be sealed, unreachable, or uninitialised.

Run 'vault read' to test if any secret is accessible.

Why it fails: A successful 'vault read' only proves that one specific path and token combination works; it does not verify server reachability or token validity generally, so it cannot isolate the failure. It is tempting because reading a known secret is a natural first sanity check when credentials look suspect.

The barrier is the network interface that Vault uses to communicate with the storage backend, and it must be configured with TLS certificates.

Why it fails: The barrier is not a network interface; it is a cryptographic barrier that encrypts data before it is written to storage. Network communication with storage is handled by the storage backend configuration, not the barrier. TLS certificates are used for securing client and cluster communication, not for the barrier's operation.

The barrier is the audit log that records all requests and responses, and it must be enabled before unsealing to capture initialization events.

Why it fails: Audit logs are separate devices that record requests and responses after Vault is unsealed and operational. They are not involved in the unseal process. The barrier is an encryption mechanism, not an auditing component. Enabling audit logs before unsealing is not possible because Vault is sealed and cannot process requests.

The barrier is the seal mechanism that automatically unseals Vault when it detects a trusted cloud provider's instance identity.

Why it fails: Auto-unseal uses a seal mechanism like AWS KMS or Azure Key Vault to decrypt the master key, but that is a separate feature. The barrier itself is the encryption layer that must be unsealed, whether manually or via auto-unseal. The barrier does not automatically unseal; it requires the correct unseal keys or auto-unseal configuration.

Grant both services a shared token with a policy allowing update on transit/encrypt/orders and transit/decrypt/orders.

Why it fails: A shared token with both capabilities collapses the separation the architect requires. Either service could then decrypt or encrypt at will, so a compromise of the writer yields decryption ability. Least privilege calls for distinct identities with distinct policies, not one credential carrying the union of permissions for both roles.

Grant both services update on transit/keys/orders and let the application decide which operation to call.

Why it fails: The transit/keys path manages key lifecycle, such as rotation and configuration, not encryption or decryption of data. Granting it would let either service rotate or reconfigure the key, which is a privilege escalation rather than the intended split. Application-side decisions are not an access control boundary, so a compromised writer could still call decrypt.

Grant the writer read on transit/encrypt/orders and the reader read on transit/decrypt/orders.

Why it fails: Transit encrypt and decrypt endpoints are invoked with HTTP POST and therefore require the update capability, not read. A read grant on those paths does not authorize the operation, so both services would receive permission denied errors. The correct verb for these data operations is update, which is a common source of confusion for policy authors.

Node3 has a different Vault version than the other nodes, so it is automatically demoted to a non-voter.

Why it fails: Vault does not automatically demote a node to non-voter based on version differences. While it is recommended that all nodes run the same Vault version, a version mismatch does not directly change Raft voting status. Autopilot may consider version as part of health checks, but it does not demote a voter to non-voter solely due to version. Other factors like health and stability are more relevant.

Node3 is configured as a performance standby, which prevents it from being a voter.

Why it fails: Performance standby is a feature of Vault Enterprise that allows a standby node to serve read requests. It does not affect Raft voting membership. A performance standby can still be a voter in the Raft configuration. The non-voter status is unrelated to performance standby; it is typically due to the node being newly added or unhealthy.

Node3 is a standby node and therefore cannot be a voter in the Raft configuration.

Why it fails: Standby nodes can be voters in Vault's Raft configuration. In fact, all nodes in a Vault cluster using integrated storage are typically voters, regardless of whether they are active or standby. The active/standby status is related to the Vault cluster leadership, not Raft voting membership. A standby node can and usually does participate in Raft consensus as a voter.

The token's TTL has been exceeded, causing Vault to delete the lease record.

Why it fails: If the token's TTL had been exceeded, the token itself would be expired and `vault token lookup` would fail or show it as invalid. The scenario states the token is still valid and not expired. The "lease not found" error specifically indicates the lease associated with the token is missing, not that the token's TTL was exceeded. Exceeding TTL would yield a different error such as "token expired" or the token would simply be gone.

The token was created with the -no-default-policy flag, which disables renewal.

Why it fails: The -no-default-policy flag only prevents the default policy from being attached to the token; it has no effect on renewal. Tokens can be renewable regardless of whether they have the default policy. This flag does not cause a "lease not found" error. The error is related to lease management, not policy attachment. The engineer should look for lease revocation or expiration issues instead.

The token was created with a period but no explicit max TTL, and the period has not yet elapsed.

Why it fails: Periodic tokens are a special type where the TTL is reset to the period value upon renewal. They do not produce a "lease not found" error during renewal; in fact, they are designed to be renewed indefinitely as long as the period hasn't elapsed. The error here suggests a missing lease, not a periodic token behavior. Periodic tokens are typically used for long-lived services and do not cause this specific error when renewed within the period.

The audit device

Why it fails: Audit devices log requests and responses but do not perform revocation. They are passive observers. While audit logs can help diagnose why revocation failed, they are not the mechanism that revokes leases. Looking at audit devices for revocation issues would be a misunderstanding of their role.

The Vault storage backend

Why it fails: The storage backend persists data but does not actively revoke leases. Revocation is a function of Vault's core and its expiration manager. The storage backend simply stores lease metadata; it does not initiate revocation actions. Misattributing lease revocation to storage can lead to troubleshooting the wrong component.

The secrets engine plugin

Why it fails: Secrets engines create and revoke credentials when instructed, but they do not schedule or trigger revocation based on TTLs. The expiration manager calls the secrets engine's revocation endpoint when a lease expires. The secrets engine itself does not monitor lease TTLs; it responds to revocation requests from the core.

The database engine rotated its root credentials, which invalidated every outstanding dynamic credential at once.

Why it fails: Root credential rotation affects Vault's ability to create new users but does not instantly revoke all existing dynamic credentials at a synchronized two-hour mark. The failure timing aligns precisely with the configured maximum lease TTL, which is a deterministic per-lease boundary. Root rotation would not produce a clean cutoff exactly at the lease ceiling.

The application's token expired, causing all leases it created to be revoked automatically at the same time.

Why it fails: Token expiry revokes leases created by that token, but the symptom here is a renew failure at a time matching the mount's max_lease_ttl, not the token's own TTL. A token-expiry explanation would require the token TTL to coincidentally equal two hours and would also invalidate the app's ability to authenticate. The timing strongly implicates the lease ceiling instead.

The application exceeded its allowed renewal count, and Vault rejected the renewal after a fixed number of attempts.

Why it fails: Vault does not impose a fixed renewal-count limit on leases. Renewal eligibility is governed by time-based ceilings such as max_lease_ttl, not by how many times a client has renewed. A renewal-count explanation would not explain why the cutoff occurred at the two-hour mark matching the mount configuration.

Wildcard matching in Vault is greedy, so the hr wildcard also matches sibling prefixes like finance.

Why it fails: Vault wildcards match path segments at or below the specified prefix, not arbitrary sibling directories. A statement for secret/data/hr/* does not extend to secret/data/finance/payroll because the literal segment hr must appear in the request path. This misconception about greedy matching leads administrators away from the real cause, which is additional attached policies.

Reading a KV v2 secret requires only the metadata path, so the finance secret is exposed through an unrelated metadata grant.

Why it fails: Reading secret values requires the read capability on the data path; metadata access alone returns version and deletion information rather than content. Even if a metadata grant existed, it would not explain a successful read of the payroll secret's value. This option misstates how KV v2 authorization works and does not fit the reported symptom.

The policy was written with a trailing wildcard that Vault silently strips, leaving a root-level grant.

Why it fails: Vault does not strip trailing wildcards or reinterpret them into broader grants. A trailing wildcard remains a prefix match scoped to the path where it appears. If the statement truly names the hr prefix, it cannot silently expand to the finance path, so this explanation does not account for the observed access and would send troubleshooting in the wrong direction.