{"record":{"id":"e6d3df55b10bc7d1","repo":"iOfficeAI/AionUi","slug":"startuparchitecturemismatcherror","errorCode":null,"errorMessage":"StartupArchitectureMismatchError","messagePattern":"StartupArchitectureMismatchError","errorType":"exception","errorClass":"StartupArchitectureMismatchError","httpStatus":null,"severity":"critical","filePath":"packages/desktop/src/process/startup/architectureCompatibility.ts","lineNumber":79,"sourceCode":"  if (!isRosettaTranslated && !deviceSupportsArm64) {\n    return null;\n  }\n\n  return {\n    deviceArch: 'arm64',\n    expectedDownloadArch: 'arm64',\n    isPackaged: true,\n    isRosettaTranslated,\n    packageArch,\n    platform: 'darwin',\n    stage: 'startup_architecture_check',\n  };\n}\n\nexport function assertStartupArchitectureCompatible(env: StartupArchitectureCompatibilityEnv = {}): void {\n  const mismatch = detectStartupArchitectureMismatch(env);\n  if (!mismatch) return;\n  throw new StartupArchitectureMismatchError(mismatch);\n}\n","sourceCodeStart":61,"sourceCodeEnd":81,"githubUrl":"https://github.com/iOfficeAI/AionUi/blob/711aa0550ee183ea495dc33e2c05c7943b70a60a/packages/desktop/src/process/startup/architectureCompatibility.ts#L61-L81","documentation":"StartupArchitectureMismatchError is thrown by assertStartupArchitectureCompatible when detectStartupArchitectureMismatch finds the running app binary's architecture does not match the host CPU architecture (e.g. x64 build running on arm64 Windows/macOS, or vice versa, typically via Rosetta or x86 emulation).","triggerScenarios":"App is launched under CPU translation: arm64 machine running an x64 build (Rosetta on macOS, emulation on Windows ARM), or an x64 machine somehow running an arm64 binary — detectStartupArchitectureMismatch compares process/arch flags from the StartupArchitectureCompatibilityEnv and returns a mismatch object which this assert throws on.","commonSituations":"User downloaded the wrong .dmg/.exe/.AppImage architecture variant; Windows-on-ARM or Apple Silicon Mac running an Intel build; CI images with emulated architectures.","solutions":["Download the build matching the host CPU architecture (arm64 installer on Apple Silicon / Windows ARM; x64 on Intel)","On Apple Silicon, check 'Kind' in Activity Monitor to confirm whether the app runs under Rosetta, then switch builds","If intentional emulation is required, bypass/suppress the assertion via its env-based escape hatch in StartupArchitectureCompatibilityEnv","Publish architecture-correct installers and make download pages auto-detect the customer's architecture"],"exampleFix":null,"handlingStrategy":"type-guard","validationCode":"import arch from 'node:process';\n// or preflight: if (detectStartupArchitectureMismatch(env)) { show guidance dialog, skip boot }","typeGuard":"function isArchMismatch(e: unknown): e is Error & { name: 'StartupArchitectureMismatchError' } {\n  return e instanceof Error && e.name === 'StartupArchitectureMismatchError';\n}","tryCatchPattern":"catch (err) {\n  if (isArchMismatch(err)) {\n    showArchGuidanceDialog(err.message); // point user to correct build\n    app.exit(1);\n  }\n  throw err;\n}","preventionTips":["Distribute architecture-detected downloads","Test builds on Apple Silicon and Windows ARM","Catch this error at the top level and show a friendly 'download the arm64 build' message"],"tags":["startup","architecture","cpu","platform-mismatch"],"backgroundTag":"architecture-mismatch","analyzedSha":"711aa0550ee183ea495dc33e2c05c7943b70a60a","analyzedAt":"2026-08-28T07:56:06.558Z","schemaVersion":2},"datasetVersion":"2026-08-28T11:17:15.048Z"}