hashicorp/terraform · error

lock ID %q does not match existing lock ID "%s/%s"

Error message

lock ID %q does not match existing lock ID "%s/%s"

What it means

Emitted by remoteClient.Unlock (backend_state.go:247-256) on the force-unlock branch where r.lockInfo is nil (the client has no recorded lock) and the provided `id` does not equal "organization/workspace". Force-unlock is only permitted when the caller supplies the canonical workspace identifier; any other value is rejected before Workspaces.ForceUnlock is invoked.

Source

Thrown at internal/backend/remote/backend_state.go:249

					return err
				}
				// This will not be retried
				return &errorUnlockFailed{innerError: err}
			}
			return nil
		})

		if err != nil {
			lockErr.Err = err
			return lockErr
		}

		return nil
	}

	// Verify the optional force-unlock lock ID.
	if r.organization+"/"+r.workspace.Name != id {
		lockErr.Err = fmt.Errorf(
			"lock ID %q does not match existing lock ID \"%s/%s\"",
			id,
			r.organization,
			r.workspace.Name,
		)
		return lockErr
	}

	// Force unlock the workspace.
	_, err := r.client.Workspaces.ForceUnlock(ctx, r.workspace.ID)
	if err != nil {
		lockErr.Err = err
		return lockErr
	}

	return nil
}

View on GitHub (pinned to c9def3e214)

Solutions

1. Pass the canonical lock ID "<organization>/<workspace>" as shown in error 429's message to the force-unlock path.
2. Re-read the lock error to obtain the exact "org/workspace" string and use that verbatim.
3. If you have the internal workspace ID instead, look up org and name via the TFC API and reconstruct the canonical form.

Example fix

// before
client.Unlock("ws-abc123")  // internal ID, not canonical -> mismatch

// after
client.Unlock("myorg/dev")   // canonical "organization/workspace"

// Validate the canonical force-unlock id format before calling the API.
want := r.organization + "/" + r.workspace.Name
if r.lockInfo == nil && id != want {
    return fmt.Errorf("force-unlock id must be %q (got %q)", want, id)
}

When it happens

Trigger: Calling Unlock with no prior recorded lockInfo and an id that is not exactly "<organization>/<workspace>" — e.g. passing a raw workspace ID, a UUID, or an empty string when trying to force-unlock.

Common situations: User or automation runs `terraform force-unlock <wrong-id>` where the ID is the workspace's internal ID rather than the org/name canonical form; wrapper passes the wrong identifier format.

Related errors

• %s (lock ID: "%s/%s")
• error uploading state: %v
• lock ID does not match existing lock
• Error locking state: %s
• failed to lock azure state: %s

AI-assisted analysis of hashicorp/terraform@c9def3e214 (2026-08-07). Data as JSON: /api/errors/3faedea9cba4326a. Report an issue: GitHub.