etcd — lease expired before keepalive

etcd returns lease not found because the lease TTL expired before a keepalive was sent, causing attached keys to be deleted automatically.

advanceddebuggingetcddistributed

Symptoms

error: etcdserver: requested lease not found
Keys attached to the lease disappear unexpectedly
Keepalive calls are too infrequent for the lease TTL

Possible causes

The lease TTL is too short for the keepalive interval
Network latency delays keepalive packets past the TTL
The client crashed and stopped sending keepalives

Diagnosis steps

Check active leases

etcdctl lease list

Interpretation

Shows active leases; if the lease is gone, it expired.

Review keepalive interval vs TTL

grep -n "keepAlive|TTL" src/etcd-client.ts

Interpretation

The keepalive interval should be less than half the TTL.

Root cause

The lease TTL expired without a keepalive, so etcd revoked the lease and deleted all keys attached to it.

Fix

Increase the lease TTL, reduce the keepalive interval, and handle lease expiration by recreating the lease and re-attaching keys.

Verify the fix

Grant a lease, send keepalives, and confirm it remains active; stop keepalives and verify the lease expires after the TTL.

Symptom walkthrough

etcd returns lease not found because the lease TTL expired before a keepalive was sent, causing attached keys to be deleted automatically. The error appears in production but may not surface in local development because the conditions that trigger it depend on the deployment environment or runtime configuration. Understanding the full symptom set helps distinguish this issue from similar errors.

Diagnosis in practice

Follow the diagnosis steps in the frontmatter to isolate the cause. Each step includes a command and an interpretation of the output. The goal is to narrow down whether the issue is in the configuration, the runtime, or the application code. Reproduce the error in a minimal setup before applying a fix.

Root cause

The lease TTL expired without a keepalive, so etcd revoked the lease and deleted all keys attached to it.

Fix

Increase the lease TTL, reduce the keepalive interval, and handle lease expiration by recreating the lease and re-attaching keys. After applying the fix, monitor the system to confirm the error does not recur under load or in different environments.

Verification

Grant a lease, send keepalives, and confirm it remains active; stop keepalives and verify the lease expires after the TTL. If the verification passes, the fix is confirmed; if not, re-examine the diagnosis steps for missed contributing factors.

Diagnostic commands

Run these commands to reproduce and diagnose the issue:

etcdctl lease list
grep -n "keepAlive|TTL" src/etcd-client.ts