OnStart signature does not match expected signature: 'func()

Error message

OnStart signature does not match expected signature: 'func() int'

What it means

If the plugin also exports OnStart, packet.proxy asserts it to func() int and calls it during Configure. A non-nil OnStart symbol with any other signature fails the type assertion and Configure returns this error quoting the expected signature.

Source

Thrown at modules/packet_proxy/packet_proxy_linux.go:159

		}

		mod.Info("loading packet proxy plugin from %s ...", mod.pluginPath)

		var ok bool
		var sym plugin.Symbol

		if mod.plugin, err = plugin.Open(mod.pluginPath); err != nil {
			return
		} else if sym, err = mod.plugin.Lookup("OnPacket"); err != nil {
			return
		} else if mod.queueCb, ok = sym.(func(q *nfqueue.Nfqueue, a nfqueue.Attribute) int); !ok {
			return fmt.Errorf("Symbol OnPacket is not a valid callback function.")
		}

		if sym, err = mod.plugin.Lookup("OnStart"); err == nil {
			var onStartCb func() int
			if onStartCb, ok = sym.(func() int); !ok {
				return fmt.Errorf("OnStart signature does not match expected signature: 'func() int'")
			} else {
				var result int
				if result = onStartCb(); result != 0 {
					return fmt.Errorf("OnStart returned non-zero result. result=%d", result)
				}
			}
		}
	} else {
		mod.Warning("no plugin set")
	}

	config := nfqueue.Config{
		NfQueue:      uint16(mod.queueNum),
		Copymode:     nfqueue.NfQnlCopyPacket,
		AfFamily:     syscall.AF_INET,
		MaxPacketLen: 0xFFFF,
		MaxQueueLen:  0xFF,
		WriteTimeout: 15 * time.Millisecond,

View on GitHub (pinned to 8eca2820f3)

Solutions

Make the plugin's OnStart exactly: func OnStart() int
Return 0 on success, non-zero on failure inside the plugin
Rebuild the plugin with the same Go version as the host bettercap binary
If no startup hook is needed, remove OnStart entirely (Lookup failing is handled gracefully)

Example fix

// before (plugin)
func OnStart(cfg Config) error { ... }
// after
func OnStart() int { setup(); return 0 }

Defensive patterns

Strategy: type-guard

Validate before calling

// before shipping the plugin, assert OnStart's shape at build time:
// var _ func() int = OnStart

Type guard

func isOnStart(sym plugin.Symbol) bool {
    _, ok := sym.(func() int)
    return ok
}

Try / catch

if err := mod.Start(); err != nil {
    if strings.Contains(err.Error(), "OnStart signature") {
        log.Fatalf("plugin OnStart must be exactly func() int; got another shape")
    }
    return err
}

Prevention

Declare OnStart strictly as func OnStart() int — no params, int return
Add var _ func() int = OnStart in the plugin for compile-time checking
Rebuild the plugin whenever bettercap's expected hook signatures change

When it happens

Trigger: Plugin exports OnStart with parameters, a different return type (e.g. error instead of int), or as a non-function symbol; Lookup succeeds but the assertion to func() int fails.

Common situations: Plugin authors return error from OnStart out of habit, or add context parameters; stale plugin compiled from older example code with a different OnStart shape.

Related errors

AI-assisted analysis of bettercap/bettercap@8eca2820f3 (2026-09-02). Data as JSON: /api/errors/cac3b9c9d755a392. Report an issue: GitHub.