Core startup is unavailable because startup safety checks di

Error message

Core startup is unavailable because startup safety checks did not pass

What it means

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.

Source

Thrown at src/main/core/manager.ts:140

  return Boolean(child && !child.killed && child.exitCode === null && child.signalCode === null)
}

export function beginCoreInitialization(): void {
  coreOperationPhase = 'initializing'
}

export function completeCoreInitialization(canStart: boolean): void {
  if (coreOperationPhase !== 'shutting-down') {
    coreOperationPhase = canStart ? 'ready' : 'blocked'
  }
}

function ensureCoreOperationAllowed(): void {
  if (coreOperationPhase === 'initializing') {
    throw new Error('Core is still initializing')
  }
  if (coreOperationPhase === 'blocked') {
    throw new Error('Core startup is unavailable because startup safety checks did not pass')
  }
  if (coreOperationPhase === 'shutting-down') {
    throw new Error('Core startup was cancelled because the application is shutting down')
  }
}

function ensureNotShuttingDown(): void {
  if (coreOperationPhase === 'shutting-down') {
    throw new Error('Core startup was cancelled because the application is shutting down')
  }
}

function runCoreOperation<T>(operation: () => Promise<T>): Promise<T> {
  const current = coreOperationTail.then(operation, operation)
  coreOperationTail = current.then(
    () => undefined,
    () => undefined
  )

View on GitHub (pinned to 911e090537)

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

Example fix

// before
await startCore()
// after
if (isCoreReady()) { await startCore() } else { await reinitializeCoreWithValidConfig() }

Defensive patterns

Strategy: validation

Validate before calling

if (typeof isCoreReady === 'function' && !isCoreReady()) {
  throw new Error('Core operations unavailable: startup safety checks failed')
}
await startCore()

Type guard

function isCorePhaseReady(phase: string): phase is 'ready' {
  return phase === 'ready'
}

Try / catch

try {
  await startCore()
} catch (err) {
  if (err.message.includes('startup safety checks did not pass')) {
    // surface config/env failure to user, do not retry blindly
  } else throw err
}

Prevention

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

When it happens

Trigger: 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'.

Common situations: 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.

Related errors

AI-assisted analysis of mihomo-party-org/clash-party@911e090537 (2026-08-30). Data as JSON: /api/errors/fed2d136111b18b0. Report an issue: GitHub.