caddyserver/caddy · error · APIError

method not allowed

Error message

method not allowed

What it means

Returned by the admin API's handleStop handler when the request method is not POST. Stopping Caddy via the /stop endpoint is a state-changing action, so only POST is accepted; anything else gets HTTP 405 'method not allowed'.

Source

Thrown at admin.go:1131

	if !ok {
		return APIError{
			HTTPStatus: http.StatusNotFound,
			Err:        fmt.Errorf("unknown object ID '%s'", id),
		}
	}

	// piece the full URL path back together
	parts = append([]string{expanded}, parts[3:]...)
	r.URL.Path = path.Join(parts...)

	return errInternalRedir
}

func handleStop(w http.ResponseWriter, r *http.Request) error {
	if r.Method != http.MethodPost {
		return APIError{
			HTTPStatus: http.StatusMethodNotAllowed,
			Err:        fmt.Errorf("method not allowed"),
		}
	}

	exitProcess(context.Background(), Log().Named("admin.api"))
	return nil
}

func parseCanonicalArrayIndex(idx string) (int, error) {
	if idx == "" {
		return 0, fmt.Errorf("empty index")
	}
	i, err := strconv.Atoi(idx)
	if err != nil {
		return 0, err
	}
	if strconv.Itoa(i) != idx {
		return 0, fmt.Errorf("non-canonical array index")
	}

View on GitHub (pinned to 50e54ee279)

Solutions

1. Send POST: curl -X POST http://localhost:2019/stop
2. If you only meant to inspect state, use GET /config/ instead of /stop

Example fix

# before
curl http://localhost:2019/stop
# after
curl -X POST http://localhost:2019/stop

curl -X POST http://localhost:2019/stop  # always POST; never GET

When it happens

Trigger: GET http://localhost:2019/stop, or PUT/DELETE on /stop. Any non-POST request to the stop endpoint.

Common situations: Browsing to /stop in a web browser (which issues GET); REST clients defaulting to GET; scripts that confuse /stop with the read-only /config endpoints which do allow GET.

Related errors

• method not allowed
• request path is missing object ID
• malformed object path
• unknown object ID '%s'
• malformed If-Match header; expect quoted string

AI-assisted analysis of caddyserver/caddy@50e54ee279 (2026-08-15). Data as JSON: /api/errors/4e1010866c38cd13. Report an issue: GitHub.