{"record":{"id":"4a055ce862772750","repo":"moeru-ai/airi","slug":"failed-to-apply-server-channel-configuration","errorCode":null,"errorMessage":"Failed to apply server channel configuration","messagePattern":"Failed to apply server channel configuration","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"apps/stage-tamagotchi/src/main/services/airi/channel-server/index.ts","lineNumber":504,"sourceCode":"\n      channelServerConfigStore.update(next)\n      return next\n    }\n    catch (error) {\n      useLogg('main/server-runtime').withError(error).error('Failed to apply server channel configuration')\n      if (runtimeChanged) {\n        const previousRuntimeOptions = await resolveServerRuntimeOptions(current)\n\n        try {\n          await params.serverChannel.updateConfig(previousRuntimeOptions)\n          await params.serverChannel.restart()\n        }\n        catch (rollbackError) {\n          useLogg('main/server-runtime').withError(rollbackError).error('Failed to restore previous server channel configuration')\n        }\n      }\n\n      throw new Error(errorMessageFrom(error) ?? 'Failed to apply server channel configuration')\n    }\n  })\n}\n\nexport type { Server as ServerChannel }\n","sourceCodeStart":486,"sourceCodeEnd":510,"githubUrl":"https://github.com/moeru-ai/airi/blob/27111382b4a79a7e983289d6e983a06af185ed0f/apps/stage-tamagotchi/src/main/services/airi/channel-server/index.ts#L486-L510","documentation":"Thrown by the electronApplyServerChannelConfig handler after the underlying updateConfig/restart (runtime changed) or start (no runtime change) threw. The handler first attempts to roll back to the previous runtime options and restart, then rethrows the original error (via errorMessageFrom, defaulting to the generic message only if the cause had no message). The rollback failure is logged separately but does not change the rethrown error.","triggerScenarios":"Calling applyServerChannelConfig with a payload that passes normalizeChannelServerOptions but then fails inside serverChannel.updateConfig or serverChannel.restart/start — e.g. port 6121 already in use, certificate generation failure, hostname not bindable, or server-runtime internals rejecting.","commonSituations":"Another process occupies the server-channel port; TLS cert/key files unreadable or mkcert generation failure; switching hostname to one the OS refuses to bind; server-runtime version mismatch; applying config while a previous restart is still in flight.","solutions":["Read the wrapped cause in errorMessageFrom(error) — the generic message only appears when the cause carried no message.","Free the server-channel port (default 6121) if it is held by a stale process.","If TLS was toggled, verify mkcert/cert paths and permissions, then retry.","Confirm the requested hostname is bindable on the current OS user.","Retry after confirming rollback succeeded; check logs for 'Failed to restore previous server channel configuration' to know whether the server is now on old or broken config."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n  await electronApplyServerChannelConfig(req)\n}\ncatch (error) {\n  const msg = errorMessageFrom(error) ?? ''\n  if (msg.includes('EADDRINUSE')) /* free the port and retry */\n  if (msg.includes('certificate') || msg.includes('mkcert')) /* fix TLS config */\n  // after a rollback, re-fetch current config to know the live state\n  throw error\n}","preventionTips":["Free the server-channel port before applying config.","Validate TLS cert/key readability before toggling TLS.","Check logs for the rollback message to know whether the server is on old or broken config."],"tags":["server-channel","electron","ipc","configuration","restart","certificates"],"backgroundTag":null,"analyzedSha":"27111382b4a79a7e983289d6e983a06af185ed0f","analyzedAt":"2026-08-12T18:33:34.132Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}