{
  "schema_version": 2,
  "id": "commands/cluster-migration",
  "title": "CLUSTER MIGRATION",
  "url": "https://redis.io/docs/latest/commands/cluster-migration/",
  "summary": "Start, monitor, and cancel atomic slot migration tasks.",
  "since": "8.4.0",
  "tags": [
    "docs",
    "develop",
    "stack",
    "oss",
    "rs",
    "rc",
    "oss",
    "kubernetes",
    "clients"
  ],
  "last_updated": "2026-09-18T09:48:21+01:00",
  "page_type": "content",
  "content_hash": "48df19f928ece760f4518146c13ea6522c63d90ea43f1fe7fbe152a4be769c54",
  "sections": [
    {
      "id": "overview",
      "title": "Overview",
      "role": "overview",
      "text": "The `CLUSTER MIGRATION` command provides atomic slot migration functionality for Redis Cluster. This command allows you to import slots from other nodes, monitor the progress of migration tasks, and cancel ongoing migrations."
    },
    {
      "id": "required-arguments",
      "title": "Required arguments",
      "role": "content",
      "text": "<details open><summary><code>subcommand</code></summary>\n\nThe subcommand specifies the operation to perform:\n\n- `IMPORT start-slot end-slot [start-slot end-slot ...]`: Executes on the destination master. Accepts multiple slot ranges and triggers atomic migration for the specified ranges. Returns a task ID that you can use to monitor the status of the task.\n\n- `CANCEL ID task-id | ALL`: Cancels an ongoing migration task by its ID or cancels all tasks if `ALL` is specified. Note: Cancelling a task on the source node does not stop the migration on the destination node, which will continue retrying until it is also cancelled there.\n\n- `STATUS [ID task-id | ALL]`: Displays the status of current and completed atomic slot migration tasks. If a specific task ID is provided, it returns detailed information for that task only. If `ALL` is specified, it returns the status of all ongoing and completed tasks.\n\n</details>"
    },
    {
      "id": "examples",
      "title": "Examples",
      "role": "example",
      "text": "Import slots 0-1000 and 2000-3000 to the current node:\n\n[code example]\n\nCheck the status of all migration tasks:\n\n[code example]\n\nCheck the status of a specific migration task:\n\n[code example]\n\nCancel a specific migration task:\n\n[code example]\n\nCancel all migration tasks:\n\n[code example]"
    },
    {
      "id": "details",
      "title": "Details",
      "role": "content",
      "text": "- Cancelling a task on the source node does not automatically stop the migration on the destination node.\n- In `CLUSTER MIGRATION STATUS` output, the \"state\" field will show `completed` for successful operations.\n- Tasks with empty \"last_error\" fields indicate no errors occurred during the migration process."
    },
    {
      "id": "key-visibility-during-migration",
      "title": "Key visibility during migration",
      "role": "content",
      "text": "During atomic slot migration operations, keys in unowned slots may be filtered out from the following commands while importing or trimming is in progress:\n\n- [`KEYS`](https://redis.io/docs/latest/commands/keys)\n- [`SCAN`](https://redis.io/docs/latest/commands/scan)\n- [`RANDOMKEY`](https://redis.io/docs/latest/commands/randomkey)\n- [`CLUSTER GETKEYSINSLOT`](https://redis.io/docs/latest/commands/cluster-getkeysinslot)\n- [`DBSIZE`](https://redis.io/docs/latest/commands/dbsize)\n- [`CLUSTER COUNTKEYSINSLOT`](https://redis.io/docs/latest/commands/cluster-countkeysinslot)\n\nThe [`INFO KEYSPACE`](https://redis.io/docs/latest/commands/info) command will continue to reflect the actual number of keys, including those being imported."
    },
    {
      "id": "related-configuration",
      "title": "Related configuration",
      "role": "related",
      "text": "- `cluster-slot-migration-handoff-max-lag-bytes`: After slot snapshot completion, if remaining replication stream size falls below this threshold, the source node pauses writes to hand off slot ownership. Higher values trigger handoff earlier but may cause longer write pauses. Lower values result in shorter write pauses but may be harder to reach with steady incoming writes (default: 1MB).\n- `cluster-slot-migration-write-pause-timeout`: Maximum duration that the source node pauses writes during ASM handoff. If the destination fails to take over slots within this timeout, the source assumes migration failed and resumes writes (default: 10 seconds)."
    },
    {
      "id": "redis-software-and-redis-cloud-compatibility",
      "title": "Redis Software and Redis Cloud compatibility",
      "role": "content",
      "text": "| Redis<br />Software | Redis<br />Cloud | <span style=\"min-width: 9em; display: table-cell\">Notes</span> |\n|:----------------------|:-----------------|:------|\n| <span title=\"Not supported\">&#x274c; Standard</span><br /><span title=\"Not supported\"><nobr>&#x274c; Active-Active</nobr></span> | <span title=\"Not supported\">&#x274c; Standard</span><br /><span title=\"Not supported\"><nobr>&#x274c; Active-Active</nobr></span> |  |"
    },
    {
      "id": "return-information",
      "title": "Return information",
      "role": "returns",
      "text": "**RESP2:**\n\nFor the `IMPORT` subcommand:\n[Bulk string reply](../../develop/reference/protocol-spec#bulk-strings): task ID on success, or error message on failure.\n\nFor the `CANCEL` subcommand:\n[Integer reply](../../develop/reference/protocol-spec#integers): number of cancelled tasks.\n\nFor the `STATUS` subcommand:\n[Array reply](../../develop/reference/protocol-spec#arrays): a list of migration task details. Each task is represented as an array containing field-value pairs:\n- `id`: Task identifier\n- `slots`: Slot range being imported or migrated\n- `source`: Source node ID\n- `dest`: Destination node ID\n- `operation`: Operation type (\"import\" or \"migrate\")\n- `state`: Current state (\"completed\", \"in_progress\", etc.)\n- `last_error`: Last error message (empty if none)\n- `retries`: Number of retry attempts\n- `create_time`: Task creation timestamp\n- `start_time`: Task start timestamp\n- `end_time`: Task completion timestamp (if completed)\n- `write_pause_ms`: Write pause duration in milliseconds\n\n**RESP3:**\n\nFor the `IMPORT` subcommand:\n[Bulk string reply](../../develop/reference/protocol-spec#bulk-strings): task ID on success, or error message on failure.\n\nFor the `CANCEL` subcommand:\n[Integer reply](../../develop/reference/protocol-spec#integers): number of cancelled tasks.\n\nFor the `STATUS` subcommand:\n[Array reply](../../develop/reference/protocol-spec#arrays): a list of migration task details. Each task is represented as an array containing field-value pairs:\n- `id`: Task identifier\n- `slots`: Slot range being migrated\n- `source`: Source node ID\n- `dest`: Destination node ID\n- `operation`: Operation type (typically \"migrate\")\n- `state`: Current state (\"completed\", \"in_progress\", etc.)\n- `last_error`: Last error message (empty if none)\n- `retries`: Number of retry attempts\n- `create_time`: Task creation timestamp\n- `start_time`: Task start timestamp\n- `end_time`: Task completion timestamp (if completed)\n- `write_pause_ms`: Write pause duration in milliseconds"
    }
  ],
  "examples": [
    {
      "id": "examples-ex0",
      "language": "bash",
      "code": "CLUSTER MIGRATION IMPORT 0 1000 2000 3000",
      "section_id": "examples"
    },
    {
      "id": "examples-ex1",
      "language": "bash",
      "code": "CLUSTER MIGRATION STATUS ALL",
      "section_id": "examples"
    },
    {
      "id": "examples-ex2",
      "language": "bash",
      "code": "CLUSTER MIGRATION STATUS ID 24cf41718b20f7f05901743dffc40bc9b15db339",
      "section_id": "examples"
    },
    {
      "id": "examples-ex3",
      "language": "bash",
      "code": "CLUSTER MIGRATION CANCEL ID 24cf41718b20f7f05901743dffc40bc9b15db339",
      "section_id": "examples"
    },
    {
      "id": "examples-ex4",
      "language": "bash",
      "code": "CLUSTER MIGRATION CANCEL ALL",
      "section_id": "examples"
    }
  ]
}