Locks Actions

Locks actions coordinate access to a shared resource so two runs of the same workflow cannot overlap. This is essential for implementing the Exclusivity Pattern in your workflows.

In n8n they live under the Lock resource.

Available Operations

Lock Actions

• Acquire - Attempt to take the lock
• Check - See whether a lock is currently held
• Release - Give the lock back

Shared parameters

Key is required on all three operations, and Additional Fields is offered on all three.

Parameter	Type	Required	Description
Key	String	Yes	Unique identifier for the lock. Must contain only letters, numbers, hyphens, and underscores. Maximum 255 characters.

Under Additional Fields:

Parameter	Type	Required	Description
Include Lock Data	Boolean	No	Whether to include lock details in the output. Defaults to false.
Lock Data Field Name	String	No	The field name where lock data will be stored in the output JSON. Defaults to 8kit.
Timeout (Seconds)	Number	No	Optional timeout in seconds for lock acquisition, between 1 and 3600. Defaults to 600.

All three operations pass the incoming item through unchanged. Lock details are added only when Include Lock Data is on, under the field named by Lock Data Field Name.

Acquire

Attempt to take the lock.

Acquire Configuration

Parameter	Type	Required	Description
Key	String	Yes	Unique identifier for the lock. Must contain only letters, numbers, hyphens, and underscores. Maximum 255 characters.
Calling Function	String	Yes	Identifier for the calling function or workflow. Used to track which process acquired the lock. Defaults to n8n-workflow.

Plus the shared Additional Fields.

Acquire Outputs

Acquire has two outputs. Yes receives items whose lock was taken; No receives items that lost the race, so another run already holds the key. Wire No to whatever should happen when the work is already in flight, usually nothing.

Acquire Response

The item passes through. With Include Lock Data on, the Yes output carries:

{
  "orderId": "12345",
  "8kit": {
    "key": "order-sync",
    "callingFn": "n8n-workflow",
    "acquired": true,
    "timestamp": "2024-01-01T10:00:00.000Z",
    "timeout": 600
  }
}

On the No output the same field carries the details of the lock that is already held, when the server reports them.

Release

Give the lock back.

Release Configuration

Parameter	Type	Required	Description
Key	String	Yes	Unique identifier for the lock. Must contain only letters, numbers, hyphens, and underscores. Maximum 255 characters.

Plus the shared Additional Fields.

Release Response

One output. The item passes through, and with Include Lock Data on:

{
  "orderId": "12345",
  "8kit": {
    "key": "order-sync",
    "released": true,
    "timestamp": "2024-01-01T10:05:00.000Z"
  }
}

Check

See whether a lock is currently held.

Check Configuration

Parameter	Type	Required	Description
Key	String	Yes	Unique identifier for the lock. Must contain only letters, numbers, hyphens, and underscores. Maximum 255 characters.

Plus the shared Additional Fields.

Check Outputs

Check has two outputs. Yes receives items where the lock exists; No receives items where it does not.

Check Response

The item passes through. With Include Lock Data on and a lock present, the Yes output carries:

{
  "orderId": "12345",
  "8kit": {
    "key": "order-sync",
    "callingFn": "n8n-workflow",
    "timestamp": "2024-01-01T10:00:00.000Z",
    "timeoutSeconds": 600,
    "appId": "app123"
  }
}

Common Patterns

Exclusivity Pattern

Implement the exclusivity pattern for resource coordination:

1. Acquire the lock at the top of the workflow
2. Continue on the Yes output; leave No unwired, or log it
3. Release the lock at the end, on every path that can be reached

Step 1: Acquire
  Key: order-sync-{{ $json.shopId }}
  Calling Function: order-sync
  Additional Fields → Timeout (Seconds): 900

Step 2: (Yes output) do the work

Step 3: Release
  Key: order-sync-{{ $json.shopId }}

Timeout (Seconds) is the safety net: if the workflow dies before it reaches Release, the lock expires on its own rather than blocking every later run. Set it above the longest run you expect.

Errors

A lock conflict is not an error: it routes to the No output. Other failures raise an error carrying the HTTP status from the server. With Continue on Fail enabled the item goes to the No output with an error object holding status, message, code and details.

Next Steps

Ready to explore more actions? Check out:

1. Last Updated Actions - Enable incremental polling
2. Complete Lookup-Uniq - Map and mark in one call
3. App Info Actions - Read the app and check server health