Improve Error Reporting When Desktop Agent *adaptor* Iframe doesn't load

[robmoffat]

Minor Issue

Poor error reporting after the initial hello:

FDC3 getAgent:  �[30m�[2mSending hello message to communication iframe�[22m�[39m
index-DnkoWixp.js:76 FDC3 getAgent:  �[30m�[2mHelloHandler: Sending hello msg:
{
  "type": "WCP1Hello",
  "meta": {
    "connectionAttemptUuid": "126e53f9-3a60-4ded-9580-683f440f0de2",
    "timestamp": "2026-01-19T13:34:24.876Z"
  },
  "payload": {
    "channelSelector": true,
    "fdc3Version": "2.2",
    "resolver": true,
    "identityUrl": "https://fdc3.finos.org/toolbox/fdc3-workbench/",
    "actualUrl": "https://fdc3.finos.org/toolbox/fdc3-workbench/"
  }
}�[22m�[39m
index-DnkoWixp.js:76 FDC3 getAgent:  �[30m�[2mDesktopAgentPreloadLoader.get(): timeout (1000 ms) at 2026-01-19T13:34:25.845Z�[22m�[39m
index-DnkoWixp.js:76 FDC3 getAgent:  �[30m�[2mDesktopAgentPreloadLoader: Cleaning up�[22m�[39m
index-DnkoWixp.js:76 FDC3 getAgent:  �[30m�[2mPostMessageLoader.get(): timeout (1000 ms) at 2026-01-19T13:34:25.845Z�[22m�[39m
index-DnkoWixp.js:76 FDC3 getAgent:  �[30m�[2mPostMessageLoader: Cleaning up�[22m�[39m
index-DnkoWixp.js:76 FDC3 getAgent:  �[30m�[2mDiscovery results:  [
  {
    "status": "rejected",
    "reason": "AgentNotFound"
  },
  {
    "status": "rejected",
    "reason": "AgentNotFound"
  }
]�[22m�[39m

Area of Issue

• App Directory
• API
• Context Data
• Intents
• Desktop Agent Bridging
• Use Cases
• Other. get-agent

Issue Description

When connecting to a desktop agent, sometimes CORS can get in the way. For example, this happens when I run Sail on localhost. It tries to load an iframe called embed.html. However, if this fails to load, nothing really shows up in the log.

After digging around, I discovered the error on the network panel, but this isn't ideal:

Additional Context

[kriswest]

Tweaked title and categorization (to enhancement). I think better error reporting is a perfectly reasonable request and should definitely be implemented. The timeout on which to report the failure to load should match the discovery timeout (which an app can override via a property).

However, another thing to think about is that fact that the Desktop Agent did actually respond... I thought we were supposed to stop the timeout at that point - so an adaptor load could take longer without failing out... But you'd still want better error reporting if it fails to load...

I've jsut checked and the diagram (middle lane) shows that we should be stopping the timeout on receipt of WCP2LoadUrl: https://fdc3.finos.org/docs/api/specs/webConnectionProtocol
so you should have just been stuck there waiting for it to load the adaptor and you should NOT have gotten AgentNotFound!

[kriswest]

I've just confirmed that the implementation is NOT correct (according the WebConnection protocol)in that the timeout is NOT cleared until after the adaptor has loaded and comms was setup with it.

Here's the relevant content:

... 3. Accept the first correct response received from a candidate. Correct responses MUST correspond to either the WCP2LoadUrl or WCP3Handshake message schemas and MUST quote the same meta.connectionAttemptUuid value provided in the original WCP1Hello message. Stop the timeout when a correct response is received....
...
Create a hidden iframe within the page, set its URL to the URL provided by the payload.iframeUrl field of the message and add a handler to run when the iframe has loaded:
...
Once the frame has loaded (i.e. when the loadedHandler in the above example runs), repeat steps 1-3 above substituting the iframe's contentWindow for the candidate window objects before proceeding to step 5. A new timeout should be used to limit the amount of time that the getAgent() implementation waits for a response. If the event that this subsequent timeout is exceeded, reject Error with the ErrorOnConnect message from the AgentError enumeration.

https://fdc3.finos.org/docs/api/specs/webConnectionProtocol#12-desktop-agent-discovery

The code that needs to be fixed is split between:

• https://github.com/finos/FDC3/blob/main/packages/fdc3-get-agent/src/strategies/PostMessageLoader.ts#L66
• https://github.com/finos/FDC3/blob/main/packages/fdc3-get-agent/src/strategies/HelloHandler.ts#L110

Changing this back to bug - I think this probably should be fixed on the 2.2.x line as its incorrectly implementing the protocol

[robmoffat]

so you should have just been stuck there waiting for it to load the adaptor and you should NOT have gotten AgentNotFound!

well that doesn't sound ideal either

[kriswest]

well that doesn't sound ideal either

Nope - but not ideal in the sense that the adaptor didn't load... We need that second timeout to go in so that you can have a specific error message on the adaptor not loading (without hacking around the protocol) and so that the implementation matches the agreed protocol.

[robmoffat]

I think we just need to report the error properly. Adding/changing timeouts isn't addressing the issue I'm raising here.

[kriswest]

It is because the current implementation only has one timeout and when it expires it doesn't know why its timed out, hence you are just getting the AgentNotFound not found message. If the implementation correctly implemented the agreed protocol then the second timeout would relate only to the loading of the adaptor and the connection to that - by additionally tracking state on whether the load event has fired for the adaptor it can then give a precise message on why its failed (the adptor didn't load vs. the connection to the adaptor didn't happen).

I can probably take a look at fixing this - I'm mildly irritated with myself that I didn't spot that the implementation was not correct in the first place (had it have been you'd already have a better error message).