Tecnología · GUÍA PRÁCTICA
¿Terraform muestra “Error acquiring the state lock”? Demuestra backend y propietario antes de force-unlock
Distingue writer activo, lock abandonado, backend incorrecto y permisos; conserva el registro y elige la recuperación mínima.
El state lock de Terraform impide escritores simultáneos. El mismo error puede venir de un terminal activo, CI, sesión remota interrumpida, backend equivocado o permisos, así que no demuestra un archivo obsoleto.
Conserva el lock record y demuestra backend efectivo, objeto, workspace y owner. Solo un lock abandonado del mismo estado debe llegar a force-unlock o a romper un lease.
Conserva el error y el registro completo
Guarda el primer error antes de reintentar. Registra Lock ID, Path, Operation, Who, Version, Created e Info, además del comando, directorio, workspace y versión de Terraform. Oculta credenciales, no identidad.
Permiso denegado, tabla ausente, key incorrecta, metadata vacía y conflicto condicional son fallos distintos. Conserva código y recurso.
Demuestra backend y objeto de estado
Confirma el backend inicializado desde el directorio real y registra tipo, cuenta/proyecto, bucket/container, key/prefix y workspace. No supongas que otro checkout apunta al mismo estado.
En S3 distingue .tflock del locking DynamoDB obsoleto y revisa permisos; en GCS confirma bucket/prefix; en Azure identifica blob y lease exactos.
Descarta un propietario activo
Revisa terminales y procesos, jobs de CI, reintentos, ejecuciones remotas y concurrencia. Compara operación, usuario, hora, workspace y ruta con el lock record.
Si hay un writer activo, espera o detenlo limpiamente y deja que Terraform libere. No uses -lock=false en paralelo.
Separa bloqueo obsoleto de permisos y configuración
Un stale lock pertenece a una operación terminada cuya liberación automática falló. Wrong backend, fallback local, DeleteObject denegado, tabla ausente o metadata rota son otros fallos.
Conserva evidencia antes de reinicializar y corrige solo el permiso mínimo del lock object sin exponer secretos.
Aplica la recuperación mínima del backend
Solo para tu propio abandoned lock en la configuración verificada usa terraform force-unlock con el LOCK_ID exacto. No cambia infraestructura, pero un unlock erróneo permite otro writer.
En Azure usa Break lease solo tras la misma prueba. El lease roto no se renueva y puede tener periodo de ruptura. Nunca borres el estado.
Verifica el estado y evita recurrencia
Ejecuta un plan de solo lectura con locking normal y confirma backend, workspace, serial/versión y recursos. Revisa versioning y controles de recuperación.
Serializa writers de CI por objeto de estado y cancela jobs sustituidos de forma segura. El cierre exige un solo propietario del lock sobre el mismo estado.
