Get started
Introduction
Installation
Your first app
Tutorials
Fission tutorials
Diagnose iOS build, signing and launch failures
Core concepts
Components
State and effects
Protected routes
Server-side rendering
Styling
Testing
Deployment
Reference
API reference
Cookbook
Fission 0.16.0
Documentation version
Read the changelog →

Diagnose iOS build, signing and launch failures

Find the first failed iOS build stage and preserve the evidence needed to distinguish compilation, signing, installation and launch.
iOS

What you will build

Diagnose the actual failing boundary without exposing signing secrets or promoting an earlier success into a working app.
Identify the last successful artifact and first failing command
Separate simulator packaging from signed physical-device installation
Collect relevant logs and configuration whilst keeping credentials private
"iOS failed to launch" describes an outcome, not its cause. The app may never have compiled, its bundle may not have been assembled, signing may have been rejected or a successfully launched process may have crashed. Changing all those layers at once removes the evidence needed to tell them apart.
We will follow one real Compose app through those boundaries. Start at the earliest failing operation and keep its command, target and first useful error. A later summary line is not a reason to regenerate an unrelated host or expose signing material in a bug report.

Start with the failing project

For an existing app, use its root and preserve its current state. Create a separate practice project only if you need a small candidate:
cargo install cargo-fission
fission init ios-diagnose-ios-build-signing-and-launch-failures
cd ios-diagnose-ios-build-signing-and-launch-failures
fission add-target ios --project-dir .
cargo add serde_yaml
Follow iOS setup for the toolchain. The diagnostic below is not a reason to initialize over an existing application or reset changes which may explain the failure.

Run the finished example

fission run --target ios --project-dir .

1. Give the candidate a useful interaction to verify

The journey editor from the component tutorial provides a small shared app with real text entry and snapshot behavior. Its normal src/lib.rs starts the same screen on native and Web targets. The browser launcher does not hide missing native wiring behind a sample work order.
Keep the generated src/main.rs. For your product, keep the actual failing core; this worked example is a separate control candidate, not a replacement which makes the problem disappear.
{"id":"fission-tabs-1","tabs":[{"index":0,"label":"src/app.rs","value":"src-app-rs"},{"index":1,"label":"src/app/state.rs","value":"src-app-state-rs"},{"index":2,"label":"src/app/fact.rs","value":"src-app-fact-rs"},{"index":3,"label":"src/app/summary.rs","value":"src-app-summary-rs"},{"index":4,"label":"src/app/screen.rs","value":"src-app-screen-rs"},{"index":5,"label":"src/i18n.rs","value":"src-i18n-rs"},{"index":6,"label":"src/lib.rs","value":"src-lib-rs"},{"index":7,"label":"preview/lib.rs","value":"preview-lib-rs"},{"index":8,"label":"i18n/en-US.yaml","value":"i18n-en-us-yaml"},{"index":9,"label":"i18n/es-ES.yaml","value":"i18n-es-es-yaml"}]}
{"id":"fission-tabs-1","index":0,"label":"src/app.rs","value":"src-app-rs"}
mod fact;
mod screen;
pub mod state;
mod summary;
pub use screen::JourneyScreen;
pub use state::JourneyState;
{"id":"fission-tabs-1","index":1,"label":"src/app/state.rs","value":"src-app-state-rs"}
use fission::prelude::*;

#[derive(Clone, Debug, PartialEq, Eq)]
pub struct Journey {
    pub origin: String,
    pub destination: String,
}

#[derive(Clone, Debug, PartialEq, Eq)]
pub struct JourneyState {
    pub prepared: Option<Journey>,
    pub locale: Locale,
}

impl Default for JourneyState {
    fn default() -> Self {
        Self {
            prepared: None,
            locale: Locale::from("en-US"),
        }
    }
}

impl GlobalState for JourneyState {}
{"id":"fission-tabs-1","index":2,"label":"src/app/fact.rs","value":"src-app-fact-rs"}
use super::state::JourneyState;
use fission::prelude::*;

fission_component! {
    pub JourneyFact<JourneyState> {
        props {
            label: TextContent,
            value: String,
        }
    }
    view(fact, _state, cx) {
        let tokens = &cx.view.env().theme.tokens;
    } => Column(gap: tokens.spacing.xs, children: [
        Text(fact.label.clone()).color(tokens.colors.text_secondary),
        Text(fact.value.clone()).weight(tokens.typography.font_weight_semibold),
    ])
}
{"id":"fission-tabs-1","index":3,"label":"src/app/summary.rs","value":"src-app-summary-rs"}
use super::{
    fact::JourneyFact,
    state::{Journey, JourneyState},
};
use fission::prelude::*;

fission_component! {
    pub JourneySummary<JourneyState> {
        props { journey: Journey }
        state { show_details: bool = false }
    }
    view(summary, _state, cx) {
        let tokens = &cx.view.env().theme.tokens;
    } => Container(
        Column(gap: tokens.spacing.m, children: [
            JourneyFact(
                TextContent::Key("journey.origin".into()),
                summary.journey.origin.clone(),
                key: "origin",
            ),
            JourneyFact(
                TextContent::Key("journey.destination".into()),
                summary.journey.destination.clone(),
                key: "destination",
            ),
            Button(
                child: Text(if summary.show_details { cx.tr("journey.hide") } else { cx.tr("journey.details") }),
                key: "toggle-details",
                on_press: reduce { summary.show_details = !summary.show_details; },
            ),
            if summary.show_details { Text(cx.tr("journey.scope")) },
        ]),
    )
    .padding_all(tokens.spacing.m)
    .border(tokens.colors.border, 1.0)
    .border_radius(tokens.radii.medium)
}
{"id":"fission-tabs-1","index":4,"label":"src/app/screen.rs","value":"src-app-screen-rs"}
use super::{
    state::{Journey, JourneyState},
    summary::JourneySummary,
};
use fission::prelude::*;

fission_component! {
    pub JourneyScreen<JourneyState> {
        state {
            origin: String = String::new(),
            destination: String = String::new(),
        }
    }
    view(screen, state, cx) {
        let tokens = &cx.view.env().theme.tokens;
    } => SafeArea(
        child: Scroll(
            child: Container(Column(gap: tokens.spacing.m, children: [
                Text(cx.tr("journey.heading")).size(tokens.typography.heading2_size),
                Text(cx.tr("journey.explanation")),
                Row(gap: tokens.spacing.s, children: [
                    Button(
                        child: Text(cx.tr("language.english")), key: "english",
                        on_press: reduce { state.locale = Locale::from("en-US"); },
                    ),
                    Button(
                        child: Text(cx.tr("language.spanish")), key: "spanish",
                        on_press: reduce { state.locale = Locale::from("es-ES"); },
                    ),
                ]),
                FormControl(
                    label: Some(cx.tr("journey.origin")),
                    required: true,
                    child: TextInput(
                        value: screen.origin.clone(),
                        bind(on_input): to(screen.origin),
                    ),
                ),
                FormControl(
                    label: Some(cx.tr("journey.destination")),
                    required: true,
                    child: TextInput(
                        value: screen.destination.clone(),
                        bind(on_input): to(screen.destination),
                    ),
                ),
                if !screen.origin.trim().is_empty() && !screen.destination.trim().is_empty() {
                    Column(gap: tokens.spacing.s, children: [
                        Text(cx.tr("journey.draft")),
                        JourneySummary(
                            Journey {
                                origin: screen.origin.trim().to_owned(),
                                destination: screen.destination.trim().to_owned(),
                            },
                            key: "draft-summary",
                        ),
                    ])
                },
                Button(
                    child: Text(cx.tr("journey.prepare")), key: "prepare-journey",
                    disabled: screen.origin.trim().is_empty() || screen.destination.trim().is_empty(),
                    on_press: reduce {
                        state.prepared = Some(Journey {
                            origin: screen.origin.trim().to_owned(),
                            destination: screen.destination.trim().to_owned(),
                        });
                    },
                ),
                if let Some(journey) = &state.prepared {
                    Column(gap: tokens.spacing.s, children: [
                        Text(cx.tr("journey.prepared")),
                        JourneySummary(journey.clone(), key: "prepared-summary"),
                    ])
                },
            ]))
            .padding_all(tokens.spacing.l),
        ),
    )
}
{"id":"fission-tabs-1","index":5,"label":"src/i18n.rs","value":"src-i18n-rs"}
use fission::i18n::{Locale, TranslationBundle};
use fission::prelude::*;
use std::collections::HashMap;

pub fn create_env() -> Env {
    let mut env = Env::default();
    env.locale = Locale::from("en-US");
    for (locale, source) in [
        ("en-US", include_str!("../i18n/en-US.yaml")),
        ("es-ES", include_str!("../i18n/es-ES.yaml")),
    ] {
        let messages: HashMap<String, String> =
            serde_yaml::from_str(source).expect("valid journey translations");
        env.i18n.add_bundle(TranslationBundle {
            locale: Locale::from(locale),
            messages,
        });
    }
    env
}

pub fn sync_env(state: &crate::app::JourneyState, env: &mut Env) {
    env.locale = state.locale.clone();
}
{"id":"fission-tabs-1","index":6,"label":"src/lib.rs","value":"src-lib-rs"}
pub mod app;
mod i18n;

use app::{JourneyScreen, JourneyState};
use fission::prelude::*;

#[cfg(not(any(target_arch = "wasm32", target_os = "android", target_os = "ios")))]
pub fn run_desktop() -> anyhow::Result<()> {
    DesktopApp::<JourneyState, _>::new(JourneyScreen)
        .with_env(i18n::create_env())
        .with_sync_env(i18n::sync_env)
        .run()
}

#[cfg(any(target_os = "android", target_os = "ios"))]
pub fn run_mobile() -> anyhow::Result<()> {
    MobileApp::<JourneyState, _>::new(JourneyScreen)
        .with_env(i18n::create_env())
        .with_sync_env(i18n::sync_env)
        .run()
}

#[cfg(target_os = "android")]
#[no_mangle]
fn android_main(app_handle: AndroidApp) {
    let _ = MobileApp::<JourneyState, _>::new(JourneyScreen)
        .with_env(i18n::create_env())
        .with_sync_env(i18n::sync_env)
        .run_with_android_app(app_handle);
}

#[cfg(target_arch = "wasm32")]
#[wasm_bindgen::prelude::wasm_bindgen(start)]
pub fn run_web() -> Result<(), wasm_bindgen::JsValue> {
    console_error_panic_hook::set_once();
    WebApp::<JourneyState, _>::new(JourneyScreen)
        .with_env(i18n::create_env())
        .with_sync_env(i18n::sync_env)
        .run()
        .map_err(|error| wasm_bindgen::JsValue::from_str(&error.to_string()))
}
{"id":"fission-tabs-1","index":7,"label":"preview/lib.rs","value":"preview-lib-rs"}
mod app;
mod i18n;

use fission::prelude::*;
use wasm_bindgen::prelude::*;

#[wasm_bindgen(start)]
pub fn run() -> Result<(), JsValue> {
    console_error_panic_hook::set_once();
    WebApp::<app::JourneyState, _>::new(app::JourneyScreen)
        .with_env(i18n::create_env())
        .with_sync_env(i18n::sync_env)
        .mount("#fission-web-mount")
        .run()
        .map_err(|error| JsValue::from_str(&error.to_string()))
}
{"id":"fission-tabs-1","index":8,"label":"i18n/en-US.yaml","value":"i18n-en-us-yaml"}
journey.heading: "Prepare a journey plan"
journey.explanation: "Enter the places you want to travel between. Review the draft, then keep a prepared copy for this session."
journey.origin: "From"
journey.destination: "To"
journey.draft: "Current draft"
journey.prepare: "Prepare journey"
journey.prepared: "Prepared journey"
journey.details: "Show plan details"
journey.hide: "Hide plan details"
journey.scope: "These are the places you entered, not a calculated route or a reservation. Nothing has been sent or saved to disk."
language.english: "English"
language.spanish: "Español"
{"id":"fission-tabs-1","index":9,"label":"i18n/es-ES.yaml","value":"i18n-es-es-yaml"}
journey.heading: "Preparar un plan de viaje"
journey.explanation: "Introduce los lugares entre los que quieres viajar. Revisa el borrador y conserva una copia preparada para esta sesión."
journey.origin: "Desde"
journey.destination: "Hasta"
journey.draft: "Borrador actual"
journey.prepare: "Preparar viaje"
journey.prepared: "Viaje preparado"
journey.details: "Mostrar detalles del plan"
journey.hide: "Ocultar detalles del plan"
journey.scope: "Son los lugares que has introducido, no una ruta calculada ni una reserva. No se ha enviado ni guardado nada en disco."
language.english: "Inglés"
language.spanish: "Español"
{"id":"fission-tabs-1"}
Enter and prepare a journey, then change the draft. This establishes the task to repeat after native launch. It says nothing about the local Xcode installation, signing identity or simulator.
Show the app preview
Hide the app preview

2. Stop at the first boundary which fails

Check the toolchain before the app:
fission doctor ios --project-dir .
xcode-select -p
xcrun --sdk iphonesimulator --show-sdk-path
rustup target list --installed
If Xcode or its simulator SDK cannot be resolved, fix that selection before changing Rust application code. If the app reaches a Rust compile or linker error, keep the first diagnostic and use the target/linker guide when an archive or platform is incompatible.
fission build --target ios --project-dir .
fission devices --project-dir .
fission run --target ios --project-dir .
A successful compile does not establish successful bundle assembly or installation. Read the subsequent package, simctl and process output. Select a known simulator using the simulator guide rather than starting another build against an unknown destination.
If a simulator process starts and then exits, retain the attached runtime output. Do not call it a signing failure merely because signing is another iOS topic. Conversely, a rejected device installation has not reached the component whose layout you were about to debug.
For your actual failure, write down the last successful stage and the first failing one. The evidence should select a smaller next check, not a list of unrelated configuration changes.
Show the app preview
Hide the app preview

3. Treat device signing as its own path

The CLI's normal iOS run command targets the simulator. A physical iPhone needs a device build and signed IPA:
fission readiness package --project-dir . --target ios --format ipa --release
fission package --project-dir . --target ios --format ipa --release
Follow the iPhone installation guide and the TestFlight guide for the intended distribution path. Verify the bundle identifier, registered device, Developer Mode, selected identity and provisioning requirements as applicable. The simulator executable cannot become a device executable by being renamed.
Supply IOS_SIGNING_IDENTITY and the required provisioning profile through protected local or CI configuration. Do not commit private keys, certificates with private material, profiles or secret values, and do not paste their contents into an issue. Report the failing command, tool versions, target and a redacted diagnostic instead.
Once installation and launch work, repeat the real journey flow, both languages and keyboard interactions. The generated smoke test checks host launch/control health; it does not qualify product behavior or prove a future store submission will pass.
Keep these outcomes separate in your report: compiled, packaged, signed, installed, launched and interaction-checked. Doing so makes the next failure easier to locate without claiming that an earlier green step proved more than it did.