fix(stacker): catch shuttle is not empty when stacker is about to retrieve (#19057)

ahiuchingau · web-flow · commit 2a6180315c48 · 2025-07-29T14:55:27.000-04:00
# Overview
This PR allows error recovery for when the shuttle is already occupied
when the stacker is about to retrieve.

This error is routed to the `stacker-stalled-and-retry` route.
diff --git a/api/src/opentrons/hardware_control/modules/flex_stacker.py b/api/src/opentrons/hardware_control/modules/flex_stacker.py
@@ -59,6 +59,7 @@
     FlexStackerShuttleMissingError,
     FlexStackerShuttleLabwareError,
     FlexStackerHopperLabwareError,
+    FlexStackerShuttleNotEmptyError,
 )
 from opentrons_shared_data.module import load_tof_baseline_data
 
@@ -711,7 +712,13 @@ async def verify_shuttle_labware_presence(
         """Check whether or not a labware is detected on the shuttle."""
         result = await self.labware_detected(StackerAxis.X, direction)
         if labware_expected != result:
-            raise FlexStackerShuttleLabwareError(
+            if labware_expected:
+                raise FlexStackerShuttleLabwareError(
+                    self.device_info["serial"],
+                    shuttle_state=self.platform_state,
+                    labware_expected=labware_expected,
+                )
+            raise FlexStackerShuttleNotEmptyError(
                 self.device_info["serial"],
                 shuttle_state=self.platform_state,
                 labware_expected=labware_expected,
diff --git a/api/src/opentrons/protocol_engine/commands/command_unions.py b/api/src/opentrons/protocol_engine/commands/command_unions.py
@@ -19,6 +19,7 @@
     FlexStackerShuttleError,
     FlexStackerHopperError,
     FlexStackerLabwareRetrieveError,
+    FlexStackerShuttleOccupiedError,
 )
 
 from . import absorbance_reader
@@ -946,6 +947,7 @@
     DefinedErrorData[FlexStackerShuttleError],
     DefinedErrorData[FlexStackerHopperError],
     DefinedErrorData[FlexStackerLabwareRetrieveError],
+    DefinedErrorData[FlexStackerShuttleOccupiedError],
 ]
 
 
diff --git a/api/src/opentrons/protocol_engine/commands/flex_stacker/common.py b/api/src/opentrons/protocol_engine/commands/flex_stacker/common.py
@@ -148,6 +148,17 @@ class FlexStackerLabwareRetrieveError(ErrorOccurrence):
     errorInfo: FailedLabware
 
 
+class FlexStackerShuttleOccupiedError(ErrorOccurrence):
+    """Returned when the Flex Stacker Shuttle is occupied when it shouldn't be."""
+
+    isDefined: bool = True
+    errorType: Literal["flexStackerShuttleOccupied"] = "flexStackerShuttleOccupied"
+
+    errorCode: str = ErrorCodes.STACKER_SHUTTLE_OCCUPIED.value.code
+    detail: str = ErrorCodes.STACKER_SHUTTLE_OCCUPIED.value.detail
+    errorInfo: FailedLabware
+
+
 @dataclass
 class _LabwareDefPair:
     definition: LabwareDefinition
diff --git a/api/src/opentrons/protocol_engine/commands/flex_stacker/retrieve.py b/api/src/opentrons/protocol_engine/commands/flex_stacker/retrieve.py
@@ -12,6 +12,7 @@
     FlexStackerShuttleMissingError,
     FlexStackerHopperLabwareError,
     FlexStackerShuttleLabwareError,
+    FlexStackerShuttleNotEmptyError,
 )
 
 from ..command import (
@@ -41,6 +42,7 @@
     FlexStackerShuttleError,
     FlexStackerHopperError,
     FlexStackerLabwareRetrieveError,
+    FlexStackerShuttleOccupiedError,
     primary_location_sequence,
     adapter_location_sequence,
     lid_location_sequence,
@@ -57,6 +59,7 @@
     FlexStackerShuttleMissingError,
     FlexStackerHopperLabwareError,
     FlexStackerShuttleLabwareError,
+    FlexStackerShuttleNotEmptyError,
 ]
 
 
@@ -147,7 +150,8 @@ class RetrieveResult(BaseModel):
     DefinedErrorData[FlexStackerStallOrCollisionError]
     | DefinedErrorData[FlexStackerShuttleError]
     | DefinedErrorData[FlexStackerHopperError]
-    | DefinedErrorData[FlexStackerLabwareRetrieveError],
+    | DefinedErrorData[FlexStackerLabwareRetrieveError]
+    | DefinedErrorData[FlexStackerShuttleOccupiedError],
 ]
 
 
@@ -175,13 +179,15 @@ def handle_recoverable_error(
         | DefinedErrorData[FlexStackerShuttleError]
         | DefinedErrorData[FlexStackerHopperError]
         | DefinedErrorData[FlexStackerLabwareRetrieveError]
+        | DefinedErrorData[FlexStackerShuttleOccupiedError]
     ):
         """Handle a recoverable error raised during command execution."""
         error_map = {
             FlexStackerStallError: FlexStackerStallOrCollisionError,
             FlexStackerShuttleMissingError: FlexStackerShuttleError,
             FlexStackerHopperLabwareError: FlexStackerHopperError,
             FlexStackerShuttleLabwareError: FlexStackerLabwareRetrieveError,
+            FlexStackerShuttleNotEmptyError: FlexStackerShuttleOccupiedError,
         }
         return DefinedErrorData(
             public=error_map[type(error)](
@@ -280,6 +286,7 @@ async def execute(self, params: RetrieveParams) -> _ExecuteReturn:
                 FlexStackerShuttleMissingError,
                 FlexStackerHopperLabwareError,
                 FlexStackerShuttleLabwareError,
+                FlexStackerShuttleNotEmptyError,
             ) as e:
                 return self.handle_recoverable_error(
                     e, to_retrieve.primaryLabwareId, state_update
diff --git a/api/tests/opentrons/protocol_engine/commands/flex_stacker/test_retrieve.py b/api/tests/opentrons/protocol_engine/commands/flex_stacker/test_retrieve.py
@@ -14,6 +14,7 @@
     FlexStackerShuttleError,
     FlexStackerHopperError,
     FlexStackerLabwareRetrieveError,
+    FlexStackerShuttleOccupiedError,
 )
 from opentrons.protocol_engine.resources import ModelUtils
 
@@ -60,6 +61,7 @@
     FlexStackerShuttleMissingError,
     FlexStackerHopperLabwareError,
     FlexStackerShuttleLabwareError,
+    FlexStackerShuttleNotEmptyError,
 )
 
 
@@ -687,6 +689,12 @@ async def test_retrieve_primary_adapter_and_lid(
             ),
             FlexStackerLabwareRetrieveError,
         ),
+        (
+            FlexStackerShuttleNotEmptyError(
+                serial="123", labware_expected=True, shuttle_state=""
+            ),
+            FlexStackerShuttleOccupiedError,
+        ),
     ],
 )
 async def test_retrieve_raises_recoverable_error(
diff --git a/app/src/assets/localization/en/error_recovery.json b/app/src/assets/localization/en/error_recovery.json
@@ -142,6 +142,7 @@
   "stacker_latch_jammed_errors_occur_when": "Stacker latch jammed errors occur when labware gets stuck in between the stacker latch. This is usually caused by improperly placed labware or inaccurate labware definitions",
   "stacker_latch_will_reengage": "The stacker latch will re-engage so that you can reload the stacker. Make sure that any obstructions have been cleared.",
   "stacker_shuttle_missing_error_occurs_when": "Stacker shuttle missing errors occur when the shuttle is not placed correctly on the track. Load the stacker shuttle onto the track to proceed.",
+  "stacker_shuttle_not_empty": "Stacker Shuttle Not Empty",
   "stacker_stall_or_collision_error": "Stacker stalled",
   "stall_or_collision_detected_when": "A stall or collision is detected when the robot's motors are blocked",
   "stall_or_collision_error": "Stall or collision",
diff --git a/app/src/organisms/ErrorRecoveryFlows/RecoveryOptions/SelectRecoveryOption.tsx b/app/src/organisms/ErrorRecoveryFlows/RecoveryOptions/SelectRecoveryOption.tsx
@@ -197,9 +197,16 @@ export function getRecoveryOptions(errorKind: ErrorKind): RecoveryRoute[] {
       return STACKER_SHUTTLE_MISSING_OPTIONS
     case ERROR_KINDS.STACKER_SHUTTLE_EMPTY:
       return STACKER_SHUTTLE_EMPTY_OPTIONS
+    case ERROR_KINDS.STACKER_SHUTTLE_OCCUPIED:
+      return STACKER_SHUTTLE_OCCUPIED_OPTIONS
   }
 }
 
+export const STACKER_SHUTTLE_OCCUPIED_OPTIONS: RecoveryRoute[] = [
+  RECOVERY_MAP.STACKER_STALLED_RETRY.ROUTE,
+  RECOVERY_MAP.CANCEL_RUN.ROUTE,
+]
+
 export const STACKER_SHUTTLE_EMPTY_OPTIONS: RecoveryRoute[] = [
   RECOVERY_MAP.STACKER_SHUTTLE_EMPTY_RETRY.ROUTE,
   RECOVERY_MAP.STACKER_SHUTTLE_EMPTY_SKIP.ROUTE,
diff --git a/app/src/organisms/ErrorRecoveryFlows/constants.ts b/app/src/organisms/ErrorRecoveryFlows/constants.ts
@@ -30,6 +30,7 @@ export const DEFINED_ERROR_TYPES = {
   HOPPER_LABWARE_MISSING: 'flexStackerHopperLabwareFailed',
   STACKER_SHUTTLE_MISSING: 'flexStackerShuttleMissing',
   STACKER_SHUTTLE_EMPTY: 'flexStackerLabwareRetrieveFailed',
+  STACKER_SHUTTLE_OCCUPIED: 'flexStackerShuttleOccupied',
 } as const
 
 // Client-defined error-handling flows.
@@ -47,13 +48,15 @@ export const ERROR_KINDS = {
   STACKER_HOPPER_EMPTY: 'STACKER_HOPPER_EMPTY',
   STACKER_SHUTTLE_MISSING: 'STACKER_SHUTTLE_MISSING',
   STACKER_SHUTTLE_EMPTY: 'STACKER_SHUTTLE_EMPTY',
+  STACKER_SHUTTLE_OCCUPIED: 'STACKER_SHUTTLE_OCCUPIED',
 } as const
 
 export const STACKER_ERROR_KINDS: ErrorKind[] = [
   ERROR_KINDS.STACKER_STALLED,
   ERROR_KINDS.STACKER_SHUTTLE_MISSING,
   ERROR_KINDS.STACKER_HOPPER_EMPTY,
   ERROR_KINDS.STACKER_SHUTTLE_EMPTY,
+  ERROR_KINDS.STACKER_SHUTTLE_OCCUPIED,
 ] as const
 
 // TODO(jh, 06-14-24): Consolidate motion routes to a single route with several steps.
diff --git a/app/src/organisms/ErrorRecoveryFlows/hooks/useErrorName.ts b/app/src/organisms/ErrorRecoveryFlows/hooks/useErrorName.ts
@@ -33,6 +33,8 @@ export function useErrorName(errorKind: ErrorKind): string {
       return t('shuttle_missing')
     case ERROR_KINDS.STACKER_SHUTTLE_EMPTY:
       return t('labware_not_retrieved')
+    case ERROR_KINDS.STACKER_SHUTTLE_OCCUPIED:
+      return t('stacker_shuttle_not_empty')
     default:
       return t('error')
   }
diff --git a/app/src/organisms/ErrorRecoveryFlows/hooks/useFailedLabwareUtils.ts b/app/src/organisms/ErrorRecoveryFlows/hooks/useFailedLabwareUtils.ts
@@ -228,6 +228,7 @@ export function getRelevantFailedLabwareCmdFrom({
     case ERROR_KINDS.STACKER_SHUTTLE_MISSING:
     case ERROR_KINDS.STACKER_HOPPER_EMPTY:
     case ERROR_KINDS.STACKER_SHUTTLE_EMPTY:
+    case ERROR_KINDS.STACKER_SHUTTLE_OCCUPIED:
       return failedCommandByRunRecord as FlexStackerRetrieveRunTimeCommand
     default:
       console.error(
@@ -375,6 +376,7 @@ export function getRelevantLabwareIdFromFailedCmd(
       'flexStackerShuttleMissing',
       'flexStackerHopperLabwareFailed',
       'flexStackerLabwareRetrieveFailed',
+      'flexStackerShuttleOccupied',
     ].includes(error.errorType)
   if (recentRelevantFailedLabwareCmd == null) {
     return null
diff --git a/app/src/organisms/ErrorRecoveryFlows/utils/getErrorKind.ts b/app/src/organisms/ErrorRecoveryFlows/utils/getErrorKind.ts
@@ -57,6 +57,8 @@ export function getErrorKind(
         return ERROR_KINDS.STACKER_SHUTTLE_MISSING
       case DEFINED_ERROR_TYPES.STACKER_SHUTTLE_EMPTY:
         return ERROR_KINDS.STACKER_SHUTTLE_EMPTY
+      case DEFINED_ERROR_TYPES.STACKER_SHUTTLE_OCCUPIED:
+        return ERROR_KINDS.STACKER_SHUTTLE_OCCUPIED
       default: {
         console.error(`Unhandled error type ${errorType}`)
         return ERROR_KINDS.GENERAL_ERROR
diff --git a/shared-data/command/types/index.ts b/shared-data/command/types/index.ts
@@ -162,8 +162,17 @@ export interface RunCommandErrorFlexStackerHopperLabware
   errorInfo: { labwareId?: string }
 }
 
+export interface RunCommandErrorFlexStackerShuttleOccupied
+  extends RunCommandErrorBase {
+  errorCode: '3023'
+  errorType: 'flexStackerShuttleOccupied'
+  isDefined: true
+  errorInfo: { labwareId?: string }
+}
+
 export type RunCommandFlexStackerError =
   | RunCommandErrorFlexStackerStall
   | RunCommandErrorFlexStackerShuttleMissing
   | RunCommandErrorFlexStackerHopperLabware
   | RunCommandErrorFlexStackerShuttleLabware
+  | RunCommandErrorFlexStackerShuttleOccupied
diff --git a/shared-data/errors/definitions/1/errors.json b/shared-data/errors/definitions/1/errors.json
@@ -222,6 +222,10 @@
       "detail": "Flex Stacker Hopper Labware Detection Failed",
       "category": "roboticsInteractionError"
     },
+    "3023": {
+      "detail": "Flex Stacker Shuttle Occupied",
+      "category": "roboticsInteractionError"
+    },
     "4000": {
       "detail": "Unknown or Uncategorized Error",
       "category": "generalError"
diff --git a/shared-data/python/opentrons_shared_data/errors/codes.py b/shared-data/python/opentrons_shared_data/errors/codes.py
@@ -85,6 +85,7 @@ class ErrorCodes(Enum):
     STACKER_SHUTTLE_MISSING = _code_from_dict_entry("3020")
     STACKER_SHUTTLE_LABWARE_FAILED = _code_from_dict_entry("3021")
     STACKER_HOPPER_LABWARE_FAILED = _code_from_dict_entry("3022")
+    STACKER_SHUTTLE_OCCUPIED = _code_from_dict_entry("3023")
     GENERAL_ERROR = _code_from_dict_entry("4000")
     ROBOT_IN_USE = _code_from_dict_entry("4001")
     API_REMOVED = _code_from_dict_entry("4002")
diff --git a/shared-data/python/opentrons_shared_data/errors/exceptions.py b/shared-data/python/opentrons_shared_data/errors/exceptions.py
@@ -853,6 +853,35 @@ def __init__(
         )
 
 
+class FlexStackerShuttleNotEmptyError(RoboticsInteractionError):
+    """An error occurred when the Flex Stacker Shuttle is not empty when it should be."""
+
+    def __init__(
+        self,
+        serial: str,
+        shuttle_state: str,
+        labware_expected: bool,
+        message: Optional[str] = None,
+        detail: Optional[Dict[str, str]] = None,
+        wrapping: Optional[Sequence[EnumeratedError]] = None,
+    ) -> None:
+        """Build a FlexStackerShuttleNotEmptyError."""
+        checked_detail: Dict[str, Any] = detail or {}
+        checked_detail["serial"] = serial
+        checked_detail["shuttle_state"] = shuttle_state
+        checked_detail["labware_expected"] = labware_expected
+        if message is not None:
+            checked_message = message
+        else:
+            checked_message = f"Flex Stacker {serial} shuttle is not empty."
+        super().__init__(
+            ErrorCodes.STACKER_SHUTTLE_OCCUPIED,
+            checked_message,
+            checked_detail,
+            wrapping,
+        )
+
+
 class FirmwareUpdateRequiredError(RoboticsInteractionError):
     """An error indicating that a firmware update is required."""
 

Original file line number	Diff line number	Diff line change
`@@ -19,6 +19,7 @@`
`19`	`19`	`FlexStackerShuttleError,`
`20`	`20`	`FlexStackerHopperError,`
`21`	`21`	`FlexStackerLabwareRetrieveError,`
	`22`	`+ FlexStackerShuttleOccupiedError,`
`22`	`23`	`)`
`23`	`24`
`24`	`25`	`from . import absorbance_reader`
`@@ -946,6 +947,7 @@`
`946`	`947`	`DefinedErrorData[FlexStackerShuttleError],`
`947`	`948`	`DefinedErrorData[FlexStackerHopperError],`
`948`	`949`	`DefinedErrorData[FlexStackerLabwareRetrieveError],`
	`950`	`+ DefinedErrorData[FlexStackerShuttleOccupiedError],`
`949`	`951`	`]`
`950`	`952`
`951`	`953`
Original file line number	Diff line number	Diff line change
`@@ -33,6 +33,8 @@ export function useErrorName(errorKind: ErrorKind): string {`
`33`	`33`	`return t('shuttle_missing')`
`34`	`34`	`case ERROR_KINDS.STACKER_SHUTTLE_EMPTY:`
`35`	`35`	`return t('labware_not_retrieved')`
	`36`	`+ case ERROR_KINDS.STACKER_SHUTTLE_OCCUPIED:`
	`37`	`+ return t('stacker_shuttle_not_empty')`
`36`	`38`	`default:`
`37`	`39`	`return t('error')`
`38`	`40`	`}`