homebridge/homebridge · error

Tried to initialize a plugin which hasn't been loaded yet!

Error message

Tried to initialize a plugin which hasn't been loaded yet!

What it means

Plugin.initialize() is called after Plugin.load() has resolved the initializer function. If the plugin hasn't been loaded (load() never ran or threw earlier without surfacing), this.pluginInitializer is undefined and initialize() throws. This indicates an internal sequencing bug or a swallowed load failure.

Source

Thrown at src/plugin.ts:245

      // initializer". Helps plugin authors and users diagnose ESM/CJS
      // shape mismatches at a glance.
      const exportedKeys = pluginModule && typeof pluginModule === 'object'
        ? Object.keys(pluginModule).filter(k => k !== 'default').slice(0, 10)
        : []
      const defaultKeys = pluginModules && typeof pluginModules === 'object'
        ? Object.keys(pluginModules).slice(0, 10)
        : []
      const defaultKeysStr = defaultKeys.length > 0 ? ` with keys [${defaultKeys.join(', ')}]` : ''
      const exportedKeysStr = exportedKeys.length > 0 ? `; named exports: [${exportedKeys.join(', ')}]` : ''
      throw new Error(
        `Plugin ${this.pluginPath} does not export an initializer function from ${this.main}. Found default export of type '${typeof pluginModules}'${defaultKeysStr}${exportedKeysStr}. The plugin must default-export a function that takes the homebridge api object.`,
      )
    }
  }

  public initialize(api: API): void | Promise<void> {
    if (!this.pluginInitializer) {
      throw new Error('Tried to initialize a plugin which hasn\'t been loaded yet!')
    }

    return this.pluginInitializer(api)
  }
}

View on GitHub (pinned to edf5493034)

Solutions

1. Ensure load() completes before initialize(); in normal usage just restart Homebridge and check startup logs for an earlier plugin load error.
2. Run Homebridge in debug mode (-D) and look for the underlying load failure (e.g. bad engines, bad main path) that left the plugin unloaded.
3. If you build tooling against these internals, always await/sequence plugin.load(...) before plugin.initialize(api).
4. Report to homebridge/homebridge with debug logs if it occurs on a standard startup with no prior errors.

Example fix

// before: tool code
const plugin = new Plugin(...)
await plugin.initialize(api)
// after
const plugin = new Plugin(...)
await plugin.load()
await plugin.initialize(api)

try {
  await plugin.initialize(api)
} catch (e) {
  if ((e as Error).message.includes("hasn't been loaded")) {
    log.error('Plugin load step was skipped or failed — check earlier logs')
  }
}

When it happens

Trigger: PluginManager calls plugin.initialize(api) on a Plugin instance whose load() step was skipped or failed; this.pluginInitializer remains undefined because load() never completed.

Common situations: Framework-level race/bug in plugin loading; user code constructing Plugin manually and calling initialize() first; a load() error caught and ignored upstream leaving the plugin half-initialized.

Related errors

• Unexpected accessory registration. Plugin ${pluginIdentifier
• Unexpected platform registration. Plugin ${pluginIdentifier
• ${cannotAction} before Homebridge has finished launching. Do
• ${cannotAction}: Matter is not enabled for this bridge. api.
• Failed to unregister accessory: ${error}

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