What causes "only POST allowed" in ipfs/kubo?

Resend the request as POST with the fraction parameter: `curl -X POST -d 'fraction=5' `.

only POST allowed

Error message

only POST allowed

What it means

MutexFractionOption registers a debug HTTP endpoint that adjusts runtime.SetMutexProfileFraction at runtime. For safety it only accepts POST; any other HTTP method is rejected with a 405 status and the body 'only POST allowed'.

Source

Thrown at core/corehttp/mutex_profile.go:18

package corehttp

import (
	"net"
	"net/http"
	"runtime"
	"strconv"

	core "github.com/ipfs/kubo/core"
)

// 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
			}

View on GitHub (pinned to 329838acdf)

Solutions

Resend the request as POST with the fraction parameter: `curl -X POST -d 'fraction=5' <debug-path>`.
If you only wanted to inspect the mutex profile, use the pprof endpoint instead (GET on the debug/pprof paths).
Confirm the endpoint is enabled — it is only mounted when the corresponding debug ServeOption is part of the server configuration.

Example fix

// before
// GET /debug/mutexfraction -> 405 only POST allowed

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

Defensive patterns

Strategy: validation

Validate before calling

req, err := http.NewRequest(http.MethodPost, debugURL, strings.NewReader("fraction=5"))
if err != nil { return err }
req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
// req.Method is guaranteed POST, avoiding the 405

Try / catch

resp, err := http.DefaultClient.Do(req)
if err == nil && resp.StatusCode == http.StatusMethodNotAllowed {
    return errors.New("mutex-fraction endpoint requires POST; add -X POST to curl")
}

Prevention

Always use `-X POST` when calling the mutex-fraction debug endpoint; GET probes from browsers will 405.
Do not confuse this write-control endpoint with read-only GET pprof endpoints.
Build requests with http.NewRequest and an explicit method in automation.
Check the 405 response body — it names the exact requirement ('only POST allowed').

When it happens

Trigger: Issuing GET (or PUT/DELETE) to the mutex-fraction debug path — e.g. opening the URL in a browser or running `curl <debug-path>` without -X POST — on a daemon started with the debug/profile HTTP options enabled.

Common situations: Developers probing the profiling endpoint in a browser; automation scripts that default to GET; curl invocations missing `-X POST -d 'fraction=N'`; confusion between read-only pprof endpoints (GET) and this write-style control endpoint (POST).

Related errors

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