Engineering Failures and Lessons Learned

Inside the Failure: Diagnosing Apple iOS Deployment Issues, MAUI Runtime Crashes, and Enterprise Mobile Architecture

Abstract

Software engineering success is rarely defined by the absence of failure. Instead, successful engineering organizations distinguish themselves by their ability to systematically identify, isolate, analyze, and resolve software engineering failures. During the development of Alexia Secure Delivery and the ongoing iOS publishing initiative for World Scholars Arena, Alexia Network LLC encountered a series of complex technical challenges spanning Apple code signing, provisioning profile management, device trust relationships, .NET MAUI application architecture, iOS startup execution, Shell navigation, runtime configuration packaging, and deployment diagnostics. This article documents failures, the engineering investigation process, evidence collected during troubleshooting, and lessons learned while preparing enterprise-grade iOS applications for production deployment.

About Alexia Network LLC

Alexia Network LLC develops software platforms focused on education, accessibility, cybersecurity, and secure communications. Published and active products include: • World Scholars Arena (Android and Windows) • Alexia Secure Delivery (iOS Enterprise Secure Document Delivery Platform) At the time of writing, engineering teams were actively pursuing: • Initial Apple App Store publication of World Scholars Arena • Production deployment and App Store publication of Alexia Secure Delivery. Both initiatives required extensive interaction with Apple’s developer ecosystem and the unique deployment requirements imposed by iOS.

The Apple Ecosystem Reality

Unlike Windows, Android, or standard web deployments, Apple maintains a highly controlled software distribution model. A successful deployment requires:

Apple Developer Account Registered App Identifier Development Certificate Provisioning Profile Device Registration Keychain Trust Validation Developer Mode Activation Valid Application Bundle Identifier Correct Signing Configuration Successful Device Trust Relationship

Failure in any of these areas can prevent the application from executing.

Certificate Validation and Keychain Analysis

One of the first diagnostic activities involved verifying the certificate's installation in macOS Keychain. The engineering team executed:

security find-identity -v

Result:

3) 5AD54803BC51023C924F2F987E1F17A9AD483C6F"Apple Development: ATEM ASTOR TANGAP (34JTPBS6A6)"

3 valid identities found

This output confirmed: • Certificate installation succeeded • Private key availability was verified • Apple Development identity existed • Signing chain was operational. At this stage, code signing itself was not the root cause.

Device Trust Verification

Apple requires explicit device registration and activation of developer mode. The following command was used:

xcrun devicectl list devices

Output:

ATASTORIdentifier:C19BC474-9AF7-5750-A9D2-6DB0C64E9ED2

State: connected

Model: iPhone 12 mini (iPhone13,1)

Additional device diagnostics showed:

bootState: booted

ddiServicesAvailable: true

developerModeStatus: enabled

This established: • Physical connectivity existed • Device Developer Mode was enabled • Device Debug Interface services were available • Deployment communication paths were operational.

The False Deployment Failure

Visual Studio repeatedly reported:

Deploy failed

while simultaneously installing the application successfully on the device. Build summary:

Build: 1 succeeded 0 failed

Deploy: 0 succeeded 1 failed

The apparent contradiction highlighted an important engineering lesson. Deployment and runtime execution are separate phases. The application package successfully reached the device. The actual failure occurred during application startup.

Runtime Failure: Missing Configuration File

The first significant runtime exception appeared immediately after application launch. Evidence:

System.IO.FileNotFoundException

Could not find file

/private/var/containers/Bundle/Application/DD02C086-DCCB-4DB7-A2DB-3A924C5E27BF/AlexiaSecureDelivery.Mobile.app/appsettings.json

Root Cause: The application expected a packaged configuration file:

appsettings.json

But the file was absent from the deployed bundle. The MAUI startup process contained:

using var settingsStream = 

FileSystem.OpenAppPackageFileAsync(

"appsettings.json")

.GetAwaiter()

.GetResult();

When the file was missing, application initialization terminated.

XAML Resource Failure

Another major failure occurred within the MAUI resource loading. Observed exception:

Microsoft.Maui.Controls.Xaml.XamlParseException

Resource 'Resources/Styles/Styles.xaml' not found

The application attempted to load:

Resources/Styles/Styles.xaml

even though the file no longer existed. This produced application startup failures before page rendering began. After removing the invalid reference, the exception disappeared.

The Black Screen Investigation

Perhaps the most difficult failure involved a persistent black screen immediately after launch. Observed behavior:

Splash Screen ↓

Black Screen ↓

No Crash

This failure generated an extensive investigation because: • Deployment succeeded • Application launched • No immediate exception appeared • No user interface rendered. The presence of a splash screen was significant. It proved: • App installation succeeded • Application executable launched • iOS startup completed • MAUI initialization reached rendering stages. The failure existed deeper within application initialization.

AppShell Versus ContentPage Diagnostics

To isolate the fault, the startup architecture was modified. Original startup:

return new Window(

_serviceProvider

.GetRequiredService<AppShell>());

Diagnostic startup:

return new Window(

_serviceProvider

.GetRequiredService<MainPage>());

This experiment was separated: • Shell architecture • Navigation • Dependency injection • Rendering from one another. The black screen persisted, proving AppShell was not the sole cause.

Shell Navigation Failure

A major discovery emerged from navigation diagnostics. Navigation implementation:

await Shell.Current

.GoToAsync(

nameof(LoginPage));

Runtime exception:

System.NullReferenceException

Object reference not set to an instance of an object

Investigation showed:

Shell.Current == null

because the startup had temporarily bypassed Shell during diagnostics. The result was a navigation subsystem attempting to operate without an active Shell instance.

MainPage Initialization Investigation

The application utilized:

protected override async void OnAppearing(){

try {

await _viewModel.InitializeAsync();

} catch {}

}

The empty catch block suppressed critical startup diagnostics. This created a situation where: • Failures occurred • Exceptions were swallowed • Users observed only a black screen without any visible indication of the underlying issue. This reinforced a fundamental enterprise engineering principle: Never suppress startup exceptions without logging.

Info.plist Modernization

Several iOS startup issues were traced to legacy Info.plist configurations. Modernization included:

<key>UILaunchStoryboardName</key><string>LaunchScreen</string>

Removal of legacy entries:

<key>XSAppIconAssets</key>

and

<key>UIApplicationSceneManifest</key>

simplified application startup behavior and aligned the application with modern MAUI deployment practices.

Provisioning Profiles and App Identity

The engineering effort required: • App Identifier creation • Development profile creation • Device registration • Bundle Identifier alignment. Application Identifier:

com.alexianetwork.securedelivery

Provisioning profiles were repeatedly regenerated and validated to ensure signing consistency across: • Visual Studio • Xcode • Apple Developer Portal • Physical devices.

Secure Backend Connectivity

The mobile application required secure communication with the ASP.NET backend. Backend:

https://localhost:7125

To facilitate external device testing:

ngrok http 7125

was introduced. This created a secure HTTPS tunnel enabling iPhone connectivity to local development infrastructure. Example:

https://abc123.ngrok-free.app

Application configuration is then referenced:

{ "Api": { "BaseUrl": "https://abc123.ngrok-free.app" }}

This eliminated local network restrictions during testing.

Enterprise Lessons Learned

Several key lessons emerged.

1. Deployment Success Does Not Mean Runtime Success

Applications can install correctly and still fail immediately after launch.

2. Configuration Packaging Matters

A missing configuration file can cause the application to terminate before rendering begins.

3. Never Swallow Exceptions

Empty catch blocks convert actionable failures into invisible failures.

4. Shell Navigation Requires Shell

Navigation architecture must match application startup architecture.

5. Apple Ecosystem Troubleshooting Is Layered

Certificates, profiles, devices, keychains, entitlements, bundle identifiers, and runtime resources must all align simultaneously.

6. Black Screens Are Symptoms

The black screen was not the root cause. It was the visible manifestation of deeper initialization failures.

Conclusion

The engineering journey behind Alexia Secure Delivery and the forthcoming iOS publication of World Scholars Arena illustrates the complexity of modern Apple iOS deployment issues. The challenges encountered were not isolated bugs but interconnected failures across deployment, signing, provisioning, configuration management, runtime initialization, and user interface architecture. By systematically validating certificates, provisioning profiles, device trust relationships, MAUI resources, startup configuration, Shell navigation, and backend connectivity, Alexia Network LLC transformed a non-functional deployment into a diagnosable and ultimately solvable engineering problem. The result was not merely progress toward App Store publication but the development of a stronger, more resilient engineering foundation capable of supporting enterprise-grade secure delivery systems and educational platforms across Apple’s ecosystem. © 2026 Alexia Network LLC Published Products:

• World Scholars Arena (Android & Windows) • World Scholars Arena (iOS) • Alexia Secure Delivery (iOS Enterprise Secure Document Delivery Platform)