homebridge/homebridge · warning

Received unknown message type from parent process: ${message

Error message

Received unknown message type from parent process: ${message.id}

What it means

The child bridge's process.on('message') handler switches on message.id (a ChildProcessMessageEventType) and logs this warning in the default branch when the parent sends a message type the child does not understand. Typically caused by version mismatch between parent Homebridge and the forked child code, or third-party messages injected into the IPC channel.

Source

Thrown at src/childBridgeFork.ts:526

      childPluginFork.handleGetMatterAccessories()
      break
    }
    case ChildProcessMessageEventType.GET_MATTER_ACCESSORY_INFO: {
      childPluginFork.handleGetMatterAccessoryInfo(message.data as { uuid: string })
      break
    }
    case ChildProcessMessageEventType.MATTER_ACCESSORY_CONTROL: {
      childPluginFork.handleMatterAccessoryControl(message.data as {
        uuid: string
        cluster: string
        attributes: Record<string, unknown>
        partId?: string
        correlationId?: string
      })
      break
    }
    default: {
      Logger.internal.warn(`Received unknown message type from parent process: ${message.id}`)
      break
    }
  }
})

/**
 * Handle the sigterm shutdown signals
 */
let shuttingDown = false
function signalHandler(signal: NodeJS.Signals, signalNum: number): void {
  if (shuttingDown) {
    return
  }
  shuttingDown = true

  Logger.internal.info('Got %s, shutting down child bridge process...', signal)

  try {

View on GitHub (pinned to edf5493034)

Solutions

1. Restart Homebridge fully so parent and all child bridges run the same version
2. Ensure no other code writes raw messages to the child's IPC channel
3. Update Homebridge (and plugins using child bridges) to matching versions
4. If from a plugin sending custom IPC, register/ignore its message id explicitly

const KNOWN = new Set(Object.values(ChildProcessMessageEventType))
if (!KNOWN.has(message.id)) console.warn(`unhandled IPC message ${message.id}; version mismatch?`)

function isKnownIpcMessage(m: unknown): m is { id: ChildProcessMessageEventType } {
  return typeof m === 'object' && m !== null && typeof (m as any).id === 'string' && (m as any).id in ChildProcessMessageEventType
}

process.on('message', (m) => { if (!isKnownIpcMessage(m)) { Logger.internal.warn('ignoring unknown IPC message'); return } /* handle */ })

When it happens

Trigger: Parent sends an IPC message whose id is not one of the handled ChildProcessMessageEventType cases — e.g. newer parent version with new event types while the fork handles an older set, or a foreign message on process.send channel.

Common situations: Partial upgrade where parent and child run different code (stale process not restarted); another library or tooling writing to the IPC channel; typo'd custom message id from patched code.

Related errors

• Accessory ${data.uuid} not found - no child bridge with Matt
• Parent process did not respond to Matter port allocation req
• Parent process did not respond to port allocation request wi
• Failed to allocate Matter port for child bridge. Please spec
• Matter manager not initialized

AI-assisted analysis of homebridge/homebridge@edf5493034 (2026-08-30). Data as JSON: /api/errors/c54e39c2cf00e1a4. Report an issue: GitHub.