wailsapp/wails · error

'%s' is a known system event name

Error message

'%s' is a known system event name

What it means

RegisterEvent[Data](name) registers a typed custom event for the binding generator; it panics if the name collides with a known Wails system event name (the events.IsKnownEvent list). System events (e.g. built-in window/application lifecycle events) are reserved so EmitEvent routing and typings stay unambiguous.

Source

Thrown at v3/pkg/application/events.go:304

}

var registeredEvents sync.Map
var voidType = reflect.TypeFor[Void]()

// RegisterEvent registers a custom event name and associated data type.
// Events may be registered at most once.
// Duplicate calls for the same event name trigger a panic.
//
// The binding generator emits typing information for all registered custom events.
// [App.EmitEvent] and [Window.EmitEvent] check the data type for registered events.
// Data types are matched exactly and no conversion is performed.
//
// It is recommended to call RegisterEvent directly,
// with constant arguments, and only from init functions.
// Indirect calls or instantiations are not discoverable by the binding generator.
func RegisterEvent[Data any](name string) {
	if events.IsKnownEvent(name) {
		panic(fmt.Errorf("'%s' is a known system event name", name))
	}
	if typ, ok := registeredEvents.Load(name); ok {
		panic(fmt.Errorf("event '%s' is already registered with data type %s", name, typ))
	}

	registeredEvents.Store(name, reflect.TypeFor[Data]())
	eventRegistered(name)
}

func validateCustomEvent(event *CustomEvent) error {
	r, ok := registeredEvents.Load(event.Name)
	if !ok {
		warnAboutUnregisteredEvent(event.Name)
		return nil
	}

	typ := r.(reflect.Type)

View on GitHub (pinned to 0e754b1b40)

Solutions

1. Prefix custom event names, e.g. "myapp:user-logged-in", to avoid the system namespace
2. Check events.IsKnownEvent(name) (or the events package constants) before registering
3. After a Wails upgrade, grep the new system event list for collisions with your registered names

Example fix

// before
app.RegisterEvent[string]("WailsWindowFocus") // or any system name: panics

// after
app.RegisterEvent[string]("myapp:window-focus-changed")

if events.IsKnownEvent(name) {
    log.Fatalf("%s collides with a system event; rename it", name)
}
app.RegisterEvent[MyData](name)

// domain-prefixed event name type prevents ad-hoc system-like names
type CustomEventName string
const EventUserLogin CustomEventName = "myapp:user-login"

When it happens

Trigger: Calling RegisterEvent with a string that matches a Wails system event name, such as one of the built-in event constants.

Common situations: Choosing a short generic event name (like a system event string copied from Wails docs or emitted by runtime) for a custom event; upgrading Wails versions where new system event names were added that now collide with an existing custom event name.

Related errors

• use ShowAndGetResults for open multiple files dialog
• use ShowAndGetResult for open single file dialog
• use GetResults for open multiple files dialog
• use GetResult for open single file dialog
• binding method ID registration expects a function, got %s

AI-assisted analysis of wailsapp/wails@0e754b1b40 (2026-08-15). Data as JSON: /api/errors/b93a768bb1381d2e. Report an issue: GitHub.