hashicorp/nomad · error

Must specify a spec

Error message

Must specify a spec

What it means

Returned by PeriodicConfig.Validate() when a periodic job defines neither a single cron spec (p.Spec) nor a multi-spec list (p.Specs) — there is no schedule to run. Appended to a multierror and surfaced on job submission/validation.

Source

Thrown at nomad/structs/structs.go:5921

	if p == nil {
		return nil
	}
	np := new(PeriodicConfig)
	*np = *p
	return np
}

func (p *PeriodicConfig) Validate() error {
	if !p.Enabled {
		return nil
	}

	var mErr multierror.Error
	if p.Spec != "" && len(p.Specs) != 0 {
		_ = multierror.Append(&mErr, fmt.Errorf("Only cron or crons may be used"))
	}
	if p.Spec == "" && len(p.Specs) == 0 {
		_ = multierror.Append(&mErr, fmt.Errorf("Must specify a spec"))
	}

	// Check if we got a valid time zone
	if p.TimeZone != "" {
		if _, err := time.LoadLocation(p.TimeZone); err != nil {
			_ = multierror.Append(&mErr, fmt.Errorf("Invalid time zone %q: %v", p.TimeZone, err))
		}
	}

	switch p.SpecType {
	case PeriodicSpecCron:
		// Validate the cron spec
		if p.Spec != "" {
			if _, err := cronexpr.Parse(p.Spec); err != nil {
				_ = multierror.Append(&mErr, fmt.Errorf("Invalid cron spec %q: %v", p.Spec, err))
			}
		}
		// Validate the cron specs

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Add a `cron = "..."` (or `crons = [...]`) entry to the periodic block
2. Verify your templating/HCL rendering actually emits the cron field
3. In code, call PeriodicConfig.SetSpec(...) before Validate
4. Run `nomad job validate my.nomad.hcl` to catch it before submission

Example fix

// before
periodic {
  prohibit_overlap = true
}
// after
periodic {
  cron = "*/5 * * * * *"
  prohibit_overlap = true
}

if pc.Spec == "" && len(pc.Specs) == 0 {
    return fmt.Errorf("periodic job requires a cron or crons schedule")
}

When it happens

Trigger: Submitting a job with `type = "periodic"` and a `periodic {}` block that is empty or whose cron/crons fields are blank strings/empty lists; programmatic creation of PeriodicConfig without calling SetSpec/SetSpecs.

Common situations: Template rendering that dropped the cron line; hand-written HCL missing the cron field; SDK/API usage constructing PeriodicConfig{} without a spec; YAML/JSON conversion losing empty fields.

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

• Only cron or crons may be used
• missing secret ID
• namespace cannot contain template delimiters or parenthesis
• wait config is nil or empty
• CSI.ControllerAttachVolume: VolumeID is required

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