overFilledOrder StackHandler Error: Can't fill order with fill [-4] more than trade quantity [-3]

[adnan-trader]

@bug-or-feature : I have elaborated on: "here are the steps to make it less painful:" as it was still pretty painful!
Ref: [https://github.com//issues/1474]

Scenario: Stackhandler crashes: Trade qty expected -3, but filled -4 trades resulting in overFilledOrder error in stackhandler.
Solution: Manually delete the orders for an instrument, including parent and children?

In general, this is the type of documentation I would add to the manual for common errors encountered in production.

I have written out the steps so that others can follow/edit.

Is this how to ensure you delete the orders for the offending instrument, including parent and children?

For example:

1. Stack handler crashes: sysexecution.orders.base_orders.overFilledOrder: Can't fill order with fill [-4] more than trade quantity [-3]
2. Ensure stack handler not running.
3. Open run_stack_handler echo file, find WARNING, above python.exe : Traceback that gave the error msg in 1. above.
   e.g., WARNING stack_handler {'component': 'mongoContractOrderStackData', 'strategy_name': 'trend_100', 'instrument_code': 'NASDAQ_micro', 'contract_order_id': 93, 'instrument_order_id': 97} Can't fill order with fill [-4] more than trade quantity [-3]
4. run interactive_order_stack
5. Choose 4: Delete and clean
6. Choose 41: Delete specific order ID (CAREFUL!)
7. Broker stack [1], Contract stack [2] or instrument stack [3]? 3 (Question: Does it matter if you start at top or bottom of the stack? I chose 3)
8. Find matching 'instrument_order_id': 97 from WARNING above:
   (Order ID:97) Type best for breakout_100 NASDAQ_micro, qty [-3], fill [-3]@ price, 19720.25 Parent:no parent Children:[93]
9. Order ID 97, Confirm delete with 'Y'.
10. Repeat for Contract stack:
11. Choose 41: Delete specific order ID (CAREFUL!)
12. Broker stack [1], Contract stack [2] or instrument stack [3]? 2
13. Find 'contract_order_id': 93:
    (Order ID:93) Type best for breakout_100/NASDAQ_micro/20250600, qty [-3], fill [-3]@ price, 19720.25 Parent:97 Children:[306, 308, 310, 312, 314]
14. Order ID 93, Confirm delete with 'Y'.
15. Repeat for Broker Stack:
16. Choose 41: Delete specific order ID (CAREFUL!)
17. Broker stack [1], Contract stack [2] or instrument stack [3]? 1
18. Find matching Children from OrderID 93 in step 14.
    (Order ID:306) Type limit for breakout_100/NASDAQ_micro/20250600, qty [-1], fill [0]@ price, None Parent:93 Children:no_children
    (Order ID:308) Type limit for breakout_100/NASDAQ_micro/20250600, qty [-1], fill [-1]@ price, 19729.25 Parent:93 Children:no_children
    (Order ID:310) Type limit for breakout_100/NASDAQ_micro/20250600, qty [-1], fill [-1]@ price, 19724.75 Parent:93 Children:no_children
    (Order ID:312) Type limit for breakout_100/NASDAQ_micro/20250600, qty [-1], fill [-1]@ price, 19719.5 Parent:93 Children:no_children
    (Order ID:314) Type limit for breakout_100/NASDAQ_micro/20250600, qty [-1], fill [-1]@ price, 19716.5 Parent:93 Children:no_children
19. Selected one fill to delete: Order ID 314, Confirm delete with 'Y'.
20. Restart stackhandler

The docs say that any number of reasons can result in a mismatch between positions in DB and broker.
NOTE: I can't explain why 5 children were created nor why 4 orders were filled when 3 were expected.
I have experienced this issue now a few times and have found it difficult to figure out why. It seems to happen when opening a new position with multiple trades of qty 1 to execute and not all of them get transmitted automatically.
NOTE: I am using TWS to monitor the trades being generated as I learn and manually transmit them if they don't automatically.