| Previous | Next |
| E_APPLICATION_VIEW_EXITING | RO_E_UNSUPPORTED_FROM_MTA |
RO_E_MUST_BE_AGILE
Object must be agile across apartments
RO_E_MUST_BE_AGILE is HRESULT 2147483676 (0x8000001C) from winerror.h. AllStat describes it as “The object must support the IAgileObject interface.” In the Windows Runtime metadata, object lifetime, asynchronous operation, activation, and apartment model, the code identifies a specific failure boundary and should not be replaced by a generic COM exception.
The hexadecimal value and symbolic name this result should remain attached to the originating API and operation generation.
Decisive interpretation boundary
Before choosing recovery, verify that the object agility, marshaling behavior, originating apartment, destination apartment, and lifetime requirements are verified. If this condition cannot be proven for it, stop before consuming outputs or repeating side effects.
Also confirm that all observed objects, tokens, buffers, proxies, metadata files, or ACLs belong to the current operation generation and were not retained from an earlier attempt.
Where it is encountered
- C++/WinRT, WRL,.NET projections, or native WinRT ABI calls. Record the interface, method, component version, thread, apartment, process, and correlation ID.
- Runtime-class activation, WinMD reflection, asynchronous objects, observable state, or view lifecycle.
- Cross-thread and cross-apartment handoff between UI, ASTA, STA, MTA, broker, and background work.
The immediate focus for it is a WinRT or COM object crossing apartment or thread boundaries where the receiving contract requires <code>IAgileObject</code> support or an agile reference. Keep it attached to that operation; the same numeric severity outside the owning API does not supply enough context.
Correct handling and recovery
Use an agile implementation, create an agile reference, marshal through a supported proxy, or keep access on the originating apartment. Do not pass raw interface pointers across threads.
Backoff alone is not a repair for it; a measurable state or configuration transition must justify another attempt.
Difference from nearby HRESULTs
It is about cross-apartment capability; RPC_E_WRONG_THREAD reports use of an interface from a thread that does not own its marshaled context.
The distinction around it should be represented explicitly in control flow and operational dashboards.
Lifetime, retry, and cleanup rules
After it, determine whether the current object, interface pointer, call context, token, stream, metadata reader, asynchronous operation, or access-control instance remains valid. Release only resources owned by the failing attempt, cancel callbacks through their documented mechanism, and avoid double close, double commit, repeated activation, or replay of a non-idempotent remote method.
The retry policy for it should state the trigger, maximum attempts, cancellation owner, and reconciliation step for effects that may have completed elsewhere.
Practical scenario
A background task captures a UI-bound runtime object in a lambda. The code captures an agile data snapshot instead and dispatches UI work back to the owning apartment.
A regression test should reproduce it, assert the raw HRESULT and all relevant outputs, then correct only the decisive condition and verify the intended success or neighboring failure result.
References
- Microsoft: C++/WinRT error handling
- Microsoft: concurrency and asynchronous operations
- Microsoft: WinMD files
- Microsoft: IAgileObject
- Microsoft: COM apartments
- Microsoft: HRESULT values
Looking for a different code? Search another status or error code.