{"record":{"id":"b93a768bb1381d2e","repo":"wailsapp/wails","slug":"s-is-a-known-system-event-name","errorCode":null,"errorMessage":"'%s' is a known system event name","messagePattern":"'(.+?)' is a known system event name","errorType":"panic","errorClass":null,"httpStatus":null,"severity":"error","filePath":"v3/pkg/application/events.go","lineNumber":304,"sourceCode":"}\n\nvar registeredEvents sync.Map\nvar voidType = reflect.TypeFor[Void]()\n\n// RegisterEvent registers a custom event name and associated data type.\n// Events may be registered at most once.\n// Duplicate calls for the same event name trigger a panic.\n//\n// The binding generator emits typing information for all registered custom events.\n// [App.EmitEvent] and [Window.EmitEvent] check the data type for registered events.\n// Data types are matched exactly and no conversion is performed.\n//\n// It is recommended to call RegisterEvent directly,\n// with constant arguments, and only from init functions.\n// Indirect calls or instantiations are not discoverable by the binding generator.\nfunc RegisterEvent[Data any](name string) {\n\tif events.IsKnownEvent(name) {\n\t\tpanic(fmt.Errorf(\"'%s' is a known system event name\", name))\n\t}\n\tif typ, ok := registeredEvents.Load(name); ok {\n\t\tpanic(fmt.Errorf(\"event '%s' is already registered with data type %s\", name, typ))\n\t}\n\n\tregisteredEvents.Store(name, reflect.TypeFor[Data]())\n\teventRegistered(name)\n}\n\nfunc validateCustomEvent(event *CustomEvent) error {\n\tr, ok := registeredEvents.Load(event.Name)\n\tif !ok {\n\t\twarnAboutUnregisteredEvent(event.Name)\n\t\treturn nil\n\t}\n\n\ttyp := r.(reflect.Type)\n","sourceCodeStart":286,"sourceCodeEnd":322,"githubUrl":"https://github.com/wailsapp/wails/blob/0e754b1b40ba9044c2a1460e23b7c3de20fc5cf3/v3/pkg/application/events.go#L286-L322","documentation":"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.","triggerScenarios":"Calling RegisterEvent with a string that matches a Wails system event name, such as one of the built-in event constants.","commonSituations":"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.","solutions":["Prefix custom event names, e.g. \"myapp:user-logged-in\", to avoid the system namespace","Check events.IsKnownEvent(name) (or the events package constants) before registering","After a Wails upgrade, grep the new system event list for collisions with your registered names"],"exampleFix":"// before\napp.RegisterEvent[string](\"WailsWindowFocus\") // or any system name: panics\n\n// after\napp.RegisterEvent[string](\"myapp:window-focus-changed\")","handlingStrategy":"validation","validationCode":"if events.IsKnownEvent(name) {\n    log.Fatalf(\"%s collides with a system event; rename it\", name)\n}\napp.RegisterEvent[MyData](name)","typeGuard":"// domain-prefixed event name type prevents ad-hoc system-like names\ntype CustomEventName string\nconst EventUserLogin CustomEventName = \"myapp:user-login\"","tryCatchPattern":null,"preventionTips":["Prefix all custom event names with your app/domain namespace","After Wails upgrades, diff the system event constants against your registered names","Register events from init() with constant names so the binding generator sees them"],"tags":["events","naming","api-misuse","panic","v3"],"backgroundTag":null,"analyzedSha":"0e754b1b40ba9044c2a1460e23b7c3de20fc5cf3","analyzedAt":"2026-08-15T14:17:36.034Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}