file parameter must be true in order to specify filepath

Error message

file parameter must be true in order to specify filepath

What it means

WorkloadIdentity.Validate rejects a Filepath set while File is false. Writing the identity to a custom file path only makes sense when file-based delivery is enabled; enabling filepath without file=true is treated as a misconfiguration.

Source

Thrown at nomad/structs/workload_id.go:494

	case WIChangeModeSignal:
		if wi.ChangeSignal == "" {
			mErr.Errors = append(mErr.Errors, fmt.Errorf("change_signal must be specified when using change_mode=%q", WIChangeModeSignal))
		}
	default:
		// Unknown change_mode
		mErr.Errors = append(mErr.Errors, fmt.Errorf("invalid change_mode: %s", wi.ChangeMode))
	}

	if wi.TTL > 0 && (wi.Name == "" || wi.Name == WorkloadIdentityDefaultName) {
		mErr.Errors = append(mErr.Errors, fmt.Errorf("ttl for default identity not yet supported"))
	}

	if wi.TTL < 0 {
		mErr.Errors = append(mErr.Errors, fmt.Errorf("ttl must be >= 0"))
	}

	if wi.Filepath != "" && !wi.File {
		mErr.Errors = append(mErr.Errors, fmt.Errorf("file parameter must be true in order to specify filepath"))
	}

	return mErr.ErrorOrNil()
}

func (wi *WorkloadIdentity) Warnings() error {
	if wi == nil {
		return fmt.Errorf("must not be nil")
	}

	var mErr multierror.Error

	if n := len(wi.Audience); n == 0 {
		mErr.Errors = append(mErr.Errors, fmt.Errorf("identities without an audience are insecure"))
	} else if n > 1 {
		mErr.Errors = append(mErr.Errors, fmt.Errorf("while multiple audiences is allowed, it is more secure to use 1 audience per identity"))
	}

View on GitHub (pinned to 482b49bf1a)

Solutions

Add file = true to the identity block when specifying filepath.
Remove the filepath field if file-based delivery is not wanted.
Ensure job templating/SDK code sets File=true whenever Filepath is non-empty.

Example fix

// before
identity {
  name = "aws"
  filepath = "/secrets/aws/token"
}
// after
identity {
  name = "aws"
  file = true
  filepath = "/secrets/aws/token"
}

Defensive patterns

Strategy: validation

Validate before calling

func validateFilepath(wi *structs.WorkloadIdentity) error {
  if wi.Filepath != "" && !wi.File {
    return fmt.Errorf("filepath %q requires file = true", wi.Filepath)
  }
  return nil
}

Prevention

In HCL templates, emit file = true whenever filepath is rendered.
Treat Filepath and File as a single coupled option in helper code.
Lint identity blocks for orphaned filepath fields.

When it happens

Trigger: An identity block with filepath = "/secrets/token" but file not set to true (file = false or omitted), or structs.WorkloadIdentity{Filepath: "...", File: false} passed to Validate().

Common situations: Hand-writing HCL and setting filepath while forgetting file = true; assuming filepath implies file delivery; copying partial identity config where the file flag was stripped.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

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