What causes "params 必须是合法 JSON" in flipped-aurora/gin-vue-admin?

Ensure Params is valid JSON, typically a JSON object like {"key":"value"}.

params 必须是合法 JSON

Error message

params 必须是合法 JSON

What it means

validateTask throws "params 必须是合法 JSON" when an executor of type TimedTaskExecutorMethod has a non-empty Params byte slice that fails json.Valid. Params are stored raw and parsed at execution time, so invalid JSON would break the runner.

Source

Thrown at server/service/system/sys_timed_task.go:58

	}
	return nil
}

// validateTask 落库前统一校验(创建/更新共用)
func (s *TimedTaskService) validateTask(t *system.SysTimedTask) error {
	if t.Name == "" {
		return errors.New("任务名不能为空")
	}
	if err := s.ValidateSpec(t.Spec, t.WithSeconds); err != nil {
		return err
	}
	switch t.ExecutorType {
	case system.TimedTaskExecutorMethod:
		if _, ok := task.Get(t.MethodName); !ok {
			return fmt.Errorf("方法 %s 未注册", t.MethodName)
		}
		if len(t.Params) > 0 && !json.Valid(t.Params) {
			return errors.New("params 必须是合法 JSON")
		}
	case system.TimedTaskExecutorHTTP:
		u, err := url.Parse(t.HttpUrl)
		if err != nil || (u.Scheme != "http" && u.Scheme != "https") || u.Host == "" {
			return errors.New("httpUrl 必须是合法的 http/https 地址")
		}
		if len(t.HttpHeader) > 0 {
			var hdr map[string]string
			if err := json.Unmarshal(t.HttpHeader, &hdr); err != nil {
				return errors.New(`httpHeader 必须是 {"Key":"Value"} 形式的 JSON 对象`)
			}
		}
	default:
		return fmt.Errorf("executorType 必须为 %s 或 %s", system.TimedTaskExecutorMethod, system.TimedTaskExecutorHTTP)
	}
	return nil
}

View on GitHub (pinned to 3136500ef3)

Solutions

Ensure Params is valid JSON, typically a JSON object like {"key":"value"}.
On the client, send the object itself and let JSON serialization handle it, not a pre-stringified string.
Run json.Valid (or JSON.parse) on the payload before calling the API.
If params are optional, send an empty value rather than malformed text.

Example fix

// before
params := []byte(`{"path": /var/log}`) // invalid JSON

// after
params, _ := json.Marshal(map[string]string{"path": "/var/log"})
svc.CreateTimedTask(ctx, &system.SysTimedTask{Name: "clean", Spec: "@daily", ExecutorType: system.TimedTaskExecutorMethod, MethodName: "CleanLogs", Params: params})

Defensive patterns

Strategy: validation

Validate before calling

if len(task.Params) > 0 && !json.Valid(task.Params) {
    return errors.New("params must be valid JSON before calling the API")
}

Type guard

func validJSONParams(p []byte) bool { return len(p) == 0 || json.Valid(p) }

Try / catch

if err := svc.CreateTimedTask(ctx, task); err != nil {
    if strings.Contains(err.Error(), "params 必须是合法 JSON") {
        http.Error(w, "params must be a valid JSON object", http.StatusBadRequest)
        return
    }
    http.Error(w, err.Error(), http.StatusInternalServerError)
}

Prevention

Build params as a Go/JS object and marshal once, not from strings
Avoid double JSON.stringify on the client
Test the payload with a JSON linter before submitting
Send empty rather than malformed when params are optional

When it happens

Trigger: Creating/updating a method-type timed task with Params like `{invalid` or a bare string without quotes; client sending params as a form string instead of a JSON object; double-encoded JSON producing non-JSON bytes.

Common situations: Hand-editing task config in DB admin tools; frontend serializing an object twice (JSON.stringify of a string); copy-pasting params with trailing comments or trailing commas.

Related errors

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