ipfs/kubo · warning

parameter 'fraction' must be set

Error message

parameter 'fraction' must be set

What it means

After successfully parsing the form, the mutex-fraction endpoint requires a 'fraction' form parameter whose value sets runtime.SetMutexProfileFraction. If the parameter is absent or empty, it responds with HTTP 400 and the fixed message "parameter 'fraction' must be set".

Source

Thrown at core/corehttp/mutex_profile.go:28

)

// MutexFractionOption allows to set runtime.SetMutexProfileFraction via HTTP
// using POST request with parameter 'fraction'.
func MutexFractionOption(path string) ServeOption {
	return func(_ *core.IpfsNode, _ net.Listener, mux *http.ServeMux) (*http.ServeMux, error) {
		mux.HandleFunc(path, func(w http.ResponseWriter, r *http.Request) {
			if r.Method != http.MethodPost {
				http.Error(w, "only POST allowed", http.StatusMethodNotAllowed)
				return
			}
			if err := r.ParseForm(); err != nil {
				http.Error(w, err.Error(), http.StatusBadRequest)
				return
			}

			asfr := r.Form.Get("fraction")
			if len(asfr) == 0 {
				http.Error(w, "parameter 'fraction' must be set", http.StatusBadRequest)
				return
			}

			fr, err := strconv.Atoi(asfr)
			if err != nil {
				http.Error(w, err.Error(), http.StatusBadRequest)
				return
			}
			log.Infof("Setting MutexProfileFraction to %d", fr)
			runtime.SetMutexProfileFraction(fr)
		})

		return mux, nil
	}
}

// BlockProfileRateOption allows to set runtime.SetBlockProfileRate via HTTP
// using POST request with parameter 'rate'.

View on GitHub (pinned to 329838acdf)

Solutions

  1. Include the parameter: `curl -X POST -d 'fraction=5' <debug-path>`.
  2. Check the parameter name is exactly `fraction` (lowercase, singular).
  3. Ensure the value is non-empty — `fraction=` still triggers the error.
  4. Choose a sensible value: 0 disables mutex profiling; higher integers increase sampling detail.

Example fix

// before
curl -X POST http://127.0.0.1:<debug-port>/debug/mutexfraction  // 400: parameter 'fraction' must be set

// after
curl -X POST -d 'fraction=5' http://127.0.0.1:<debug-port>/debug/mutexfraction
Defensive patterns

Strategy: validation

Validate before calling

fraction := "5"
if fraction == "" {
    return errors.New("fraction parameter must be set and non-empty")
}
form := url.Values{"fraction": {fraction}}
req, _ := http.NewRequest(http.MethodPost, debugURL, strings.NewReader(form.Encode()))
req.Header.Set("Content-Type", "application/x-www-form-urlencoded")

Try / catch

resp, err := http.DefaultClient.Do(req)
if err == nil && resp.StatusCode == http.StatusBadRequest {
    body, _ := io.ReadAll(resp.Body)
    if strings.Contains(string(body), "must be set") {
        return errors.New("add -d 'fraction=<int>' to the request")
    }
    return fmt.Errorf("bad request: %s", body)
}

Prevention

When it happens

Trigger: POSTing to the mutex-fraction debug path without a 'fraction' field — e.g. `curl -X POST <debug-path>` with no body, or `-d 'other=1'`, or an empty `-d 'fraction='`.

Common situations: Smoke-testing the endpoint with a bare POST; scripts renamed the parameter (e.g. 'value'); copying examples that omitted the body; empty-string values trimmed by the client.

Related errors

AI-assisted analysis of ipfs/kubo@329838acdf (2026-09-03). Data as JSON: /api/errors/29a366246b644d5e. Report an issue: GitHub.