hashicorp/nomad · error

failed to parse follow field to boolean: %v

Error message

failed to parse follow field to boolean: %v

What it means

Returned by the file/log streaming endpoint's Stream handler (command/agent/fs_endpoint.go:225) when the `follow` query parameter is present but fails strconv.ParseBool. follow defaults to true, so the error only occurs when a caller explicitly supplies a value outside Go's accepted boolean literals.

Source

Thrown at command/agent/fs_endpoint.go:225

//     applied. Defaults to "start".
func (s *HTTPServer) Stream(resp http.ResponseWriter, req *http.Request) (any, error) {
	var allocID, path string
	var err error

	q := req.URL.Query()

	if allocID = strings.TrimPrefix(req.URL.Path, "/v1/client/fs/stream/"); allocID == "" {
		return nil, allocIDNotPresentErr
	}

	if path = q.Get("path"); path == "" {
		return nil, fileNameNotPresentErr
	}

	follow := true
	if followStr := q.Get("follow"); followStr != "" {
		if follow, err = strconv.ParseBool(followStr); err != nil {
			return nil, fmt.Errorf("failed to parse follow field to boolean: %v", err)
		}
	}

	var offset int64
	offsetString := q.Get("offset")
	if offsetString != "" {
		if offset, err = strconv.ParseInt(offsetString, 10, 64); err != nil {
			return nil, fmt.Errorf("error parsing offset: %v", err)
		}
	}

	origin := q.Get("origin")
	switch origin {
	case "start", "end":
	case "":
		origin = "start"
	default:
		return nil, invalidOrigin

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Send follow=true or follow=false — only Go bool literals are accepted.
2. Omit the parameter to accept the default (true).
3. Normalize client-side with strconv.FormatBool(myBool) before URL-encoding.
4. Trim whitespace and strip stray quotes from templated values before sending.

Example fix

// before
curl -N "http://localhost:4646/v1/client/fs/logs?alloc_id=abc&follow=yes"
// after
curl -N "http://localhost:4646/v1/client/fs/logs?alloc_id=abc&follow=true"

if f := q.Get("follow"); f != "" {
    if _, err := strconv.ParseBool(f); err != nil {
        return fmt.Errorf("follow must be a Go bool literal, got %q", f)
    }
}

func validFollow(s string) bool {
    if s == "" { return true }
    _, err := strconv.ParseBool(s)
    return err == nil
}

if err != nil {
    if strings.Contains(err.Error(), "failed to parse follow field") {
        // retry with the default follow=true
        q.Set("follow", "true")
    }
}

When it happens

Trigger: Calling GET /v1/client/fs/stream or /v1/client/fs/logs with follow=<v> where v is not one of 1,t,T,TRUE,true,True,0,f,F,FALSE,false,False — e.g. follow=yes, follow=on, or follow=true with a trailing space.

Common situations: Using shell-style yes/no/on/off conventions; templating injecting whitespace or quotes; languages rendering booleans differently than Go; typos like follow=truee.

Understand the failure class

Background: "Invalid query parameter" / "Failed to parse value of ...": fixing bad query string parameters across APIs — this error's family across 36 libraries.

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• error parsing limit: %v
• users: unable to parse uid/gid from username
• <combined HCL diagnostics from str.String()>
• Unable to convert Uid to an int: %w
• Unable to convert Gid to an int: %w

AI-assisted analysis of hashicorp/nomad@482b49bf1a (2026-09-04). Data as JSON: /api/errors/4ffe041f72740d97. Report an issue: GitHub.