What causes "方法 %s 未注册(需在 initialize/timer.go 经 task.Register 注册)" in flipped-aurora/gin-vue-admin?

Register the function in initialize/timer.go via task.Register(" ", fn) so it matches t.MethodName exactly

方法 %s 未注册(需在 initialize/timer.go 经 task.Register 注册)

Error message

方法 %s 未注册(需在 initialize/timer.go 经 task.Register 注册)

What it means

runMethod looks up the task function by t.MethodName in the in-process task registry (task.Get). If no function with that name was registered via task.Register in initialize/timer.go, the run fails with this message. Registration happens at application startup, so the name must match exactly at runtime.

Source

Thrown at server/service/system/sys_timed_task_runner.go:100

		ErrorMsg:    errMsg,
		Output:      truncateText(output, maxLogTextLen),
	}
	ctx := datascope.WithSystem(context.Background())
	if err := global.GVA_DB.WithContext(ctx).Create(&logRow).Error; err != nil {
		logger.Bg().Mod("timedTask").Err(err).Error("定时任务执行日志落库失败: " + t.Name)
	}
	if runErr != nil {
		logger.Bg().Mod("timedTask").Err(runErr).Error("定时任务执行失败: " + t.Name)
		s.alertFailure(t, errMsg)
	}
}

// runMethod 执行已注册本体方法。
// 超时语义: 只能标记状态, goroutine 无法强杀; 任务函数应响应 ctx 取消。
func (s *TimedTaskService) runMethod(t system.SysTimedTask) (string, error) {
	fn, ok := task.Get(t.MethodName)
	if !ok {
		return "", fmt.Errorf("方法 %s 未注册(需在 initialize/timer.go 经 task.Register 注册)", t.MethodName)
	}
	ctx, cancel := context.WithTimeout(datascope.WithSystem(context.Background()), defaultMethodTimeout)
	defer cancel()

	done := make(chan error, 1)
	go func() {
		defer func() {
			if r := recover(); r != nil {
				done <- fmt.Errorf("panic: %v", r)
			}
		}()
		done <- fn(ctx, json.RawMessage(t.Params))
	}()
	select {
	case err := <-done:
		if err != nil && errors.Is(err, context.DeadlineExceeded) {
			return "", errTaskTimeout
		}

View on GitHub (pinned to 3136500ef3)

Solutions

Register the function in initialize/timer.go via task.Register("<name>", fn) so it matches t.MethodName exactly
Fix the task row's method_name to an already-registered name (check registration list at startup)
Restart the server after adding the registration — the registry is in-process

Example fix

// before (initialize/timer.go missing)
// nothing
// after
func init() { task.Register("cleanExpiredTokens", cleanExpiredTokens) }

Defensive patterns

Strategy: validation

Validate before calling

if _, ok := task.Get(methodName); !ok {
    return fmt.Errorf("method %s is not registered", methodName)
}

Try / catch

if err := RunTask(t); err != nil {
    if strings.Contains(err.Error(), "未注册") {
        log.Warnf("task %d references unregistered method %s; register it in initialize/timer.go", t.ID, t.MethodName)
    }
}

Prevention

Register every task function in initialize/timer.go at startup and keep the list reviewed in code review
Validate method_name against task registry when the task is created via API/UI
Add a startup health check that scans enabled tasks and logs any unregistered method names

When it happens

Trigger: SysTimedTask.MethodName contains a name never passed to task.Register; the registering code was removed/renamed during refactoring; task created before a deploy that renamed the function.

Common situations: Typo or case mismatch between task row's method_name and Register call; deploy where initialize/timer.go no longer registers the method but old DB rows still reference it; multi-binary deploys where the target binary doesn't include the registration.

Related errors

AI-assisted analysis of flipped-aurora/gin-vue-admin@3136500ef3 (2026-08-31). Data as JSON: /api/errors/73afa8b24530900f. Report an issue: GitHub.