## TL;DR

The sync chain is SecretStore (how to reach Vault) then ExternalSecret (what to fetch). Check the store's auth and connectivity first, then the secret path and the target namespace permissions.

## Error

```text
kubernetes external-secrets failed to sync from vault
```

## Steps

1. Describe the SecretStore and read its status conditions. Expected: ready, or an auth/connectivity error.
2. Verify the Vault auth the store uses (role, service account, token) is valid. Expected: auth works from the cluster.
3. Check network: the operator needs to reach Vault's address from the cluster. Expected: connectivity confirmed.
4. Verify the secret path in the ExternalSecret exists in Vault. Expected: the path resolves.
5. Check the operator's RBAC can create and update Secrets in the target namespace. Expected: sync completes.

## When to use

- ExternalSecret resources stuck without synced Secrets.
- Setting up external-secrets with Vault.

## When not to use

- CSI driver secret mounts (different component).
- Vault-side permission errors (fix the Vault policy).

## Tool compatibility

- External Secrets Operator; Vault provider; Kubernetes RBAC.

## Variant phrasings

### externalsecret not syncing

Same chain to check.

### secretstore not ready vault

Auth or network.

## Why it happens

Sync needs four things: Vault reachable, auth valid, path correct, RBAC sufficient. Any one breaks the chain with a similar symptom.

## Edge cases

- Refresh intervals: a synced-but-stale secret may just be waiting for refresh.
- Namespace-scoped stores cannot read cluster-wide; match the scope.
- Vault namespace headers must be set for namespaced Vault.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_8x7px6gaI75Gvq8r7I6bbA