{"record":{"id":"fed2d136111b18b0","repo":"mihomo-party-org/clash-party","slug":"core-startup-is-unavailable-because-startup-safety","errorCode":null,"errorMessage":"Core startup is unavailable because startup safety checks did not pass","messagePattern":"Core startup is unavailable because startup safety checks did not pass","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"src/main/core/manager.ts","lineNumber":140,"sourceCode":"  return Boolean(child && !child.killed && child.exitCode === null && child.signalCode === null)\n}\n\nexport function beginCoreInitialization(): void {\n  coreOperationPhase = 'initializing'\n}\n\nexport function completeCoreInitialization(canStart: boolean): void {\n  if (coreOperationPhase !== 'shutting-down') {\n    coreOperationPhase = canStart ? 'ready' : 'blocked'\n  }\n}\n\nfunction ensureCoreOperationAllowed(): void {\n  if (coreOperationPhase === 'initializing') {\n    throw new Error('Core is still initializing')\n  }\n  if (coreOperationPhase === 'blocked') {\n    throw new Error('Core startup is unavailable because startup safety checks did not pass')\n  }\n  if (coreOperationPhase === 'shutting-down') {\n    throw new Error('Core startup was cancelled because the application is shutting down')\n  }\n}\n\nfunction ensureNotShuttingDown(): void {\n  if (coreOperationPhase === 'shutting-down') {\n    throw new Error('Core startup was cancelled because the application is shutting down')\n  }\n}\n\nfunction runCoreOperation<T>(operation: () => Promise<T>): Promise<T> {\n  const current = coreOperationTail.then(operation, operation)\n  coreOperationTail = current.then(\n    () => undefined,\n    () => undefined\n  )","sourceCodeStart":122,"sourceCodeEnd":158,"githubUrl":"https://github.com/mihomo-party-org/clash-party/blob/911e090537acdf7c50bee1c3aebecc2ef119a8b5/src/main/core/manager.ts#L122-L158","documentation":"This error is thrown by ensureCoreOperationAllowed() in src/main/core/manager.ts:140 when the core's operation phase is 'blocked'. The phase becomes 'blocked' via completeCoreInitialization(false), meaning startup safety checks (config validation, environment checks) failed during app initialization, so all core operations — startCore, stopCore, restartCoreAfterUnexpectedExit, restartCore — are refused. The library throws this to prevent running the core in an unsafe or invalid state.","triggerScenarios":"Calling startCore(), stopCore(), restartCore(), or restartCoreAfterUnexpectedExit() after initialization completed with completeCoreInitialization(false) (coreOperationPhase === 'blocked'), i.e. before the startup safety checks have passed and the phase is reset to 'ready'.","commonSituations":"Launching core operations while the app booted with an invalid config file, missing core binary, or failed pre-flight checks; or a plugin/renderer racing the app's initialization and calling startCore before the main process finished its safety checks.","solutions":["Fix the underlying startup safety-check failure (invalid config, missing core binary, bad permissions) so initialization ends with completeCoreInitialization(true)","Wait for app initialization to finish before calling any core operation; check the phase/readiness state exposed by the manager first","If the phase is stuck at 'blocked' unexpectedly, inspect logs of the startup checks that failed and restart the app after fixing them"],"exampleFix":"// before\nawait startCore()\n// after\nif (isCoreReady()) { await startCore() } else { await reinitializeCoreWithValidConfig() }","handlingStrategy":"validation","validationCode":"if (typeof isCoreReady === 'function' && !isCoreReady()) {\n  throw new Error('Core operations unavailable: startup safety checks failed')\n}\nawait startCore()","typeGuard":"function isCorePhaseReady(phase: string): phase is 'ready' {\n  return phase === 'ready'\n}","tryCatchPattern":"try {\n  await startCore()\n} catch (err) {\n  if (err.message.includes('startup safety checks did not pass')) {\n    // surface config/env failure to user, do not retry blindly\n  } else throw err\n}","preventionTips":["Gate all core calls behind app-ready initialization events","Validate config and core binary before triggering core operations","Do not call core APIs from renderers before the main process signals readiness"],"tags":["lifecycle","initialization","core-manager","state-machine"],"backgroundTag":"core-startup-blocked","analyzedSha":"911e090537acdf7c50bee1c3aebecc2ef119a8b5","analyzedAt":"2026-08-30T13:00:49.174Z","schemaVersion":2},"datasetVersion":"2026-08-30T13:17:10.514Z"}