OutSystems Image Rendering Issue – Root Cause Analysis & Resolution Report

1. Project Context
   
   Application: Sample Mobile Field Application
   Platform: OutSystems Platform
   Module Type: Mobile / Reactive Application
   Issue Area: Image rendering using BinaryData from API Base64 response
   
2. Problem Statement
   An external API was returning image data in Base64 format. The implementation flow was:
   API Response (Base64) → BinaryDataFromBase64Decode() → Assign to Structure.FileData → Pass Structure
   across multiple blocks → Bind to Image Widget (Image Content)
   
   Although:

• Base64 conversion was successful
• BinaryData existed in debugger
• Length(BinaryData) returned valid values
  the Image widget failed to render the image.

1. Observed Symptoms

• Browser rendered broken image.
• Generated image source was using the OutSystems _BinaryContent endpoint.
• Network request to the generated _BinaryContent URL returned 404 Not Found.

1. Validation Performed
   The following validations were performed:

• Confirmed API returned valid Base64 image data.
• Verified BinaryData length was non-zero.
• Re-encoded BinaryData back to Base64 successfully.
• Confirmed Base64 to Binary conversion logic was correct.

1. Root Cause Identified
   The issue was caused by BinaryData lifecycle and runtime reference management within OutSystems.
   Specifically:

• BinaryData was stored inside transient API structures.
• Structures were passed across multiple blocks.
• OutSystems generated _BinaryContent URLs successfully.
• Runtime could not later resolve the BinaryData reference.
• Resulting requests returned 404 Not Found.

1. Technical Explanation
   OutSystems does not treat BinaryData as simple raw bytes. Internally, BinaryData behaves as a runtime-managed binary reference. When an Image widget renders BinaryData:
   
2. OutSystems generates a temporary _BinaryContent URL.
   
3. Browser requests the generated URL.
   
4. OutSystems runtime attempts to retrieve the original BinaryData.
   
5. Retrieval fails if the runtime reference is no longer stable or accessible.
   
6. Final Resolution
   The issue was resolved by moving BinaryData into a dedicated runtime-managed BinaryData variable before binding it to the Image widget. Instead of directly binding Structure.FileData to the widget, a dedicated BinaryData variable was introduced and passed directly to blocks.
   
7. Corrected Architecture
   Step 1: Create a dedicated BinaryData local variable.
   Step 2: Assign decoded binary data into the dedicated variable.
   Step 3: Pass only the BinaryData variable to blocks instead of entire structures.
   Step 4: Bind the Image widget directly to the dedicated BinaryData variable.
   
8. Result After Fix
   After implementing the fix:

• Image widget rendered successfully.
• _BinaryContent endpoint resolved correctly.
• 404 errors were eliminated.
• Binary rendering became stable across blocks and screen navigation.

1. Key Learnings and Best Practices
   Recommended:

• Use dedicated BinaryData variables for rendering.
• Pass BinaryData directly between blocks.
• Use Entity-managed BinaryData for persistent images.
• Keep BinaryData ownership stable within screen lifecycle.
  Avoid:
• Binding Image widgets directly to deeply nested transient structures.
• Passing BinaryData through unstable deserialized objects.
• Relying on transient runtime references for image rendering.

Final Conclusion

The issue was not related to invalid Base64 data or incorrect binary conversion. The actual root cause was OutSystems BinaryData runtime lifecycle management across structures and blocks. The issue was resolved by moving BinaryData into a stable runtime-managed variable and binding the Image widget directly to that managed BinaryData reference