hashicorp/nomad · error

Unknown periodic specification type %q

Error message

Unknown periodic specification type %q

What it means

PeriodicConfig.Validate switches on SpecType and only recognizes the known constants (e.g. PeriodicSpecCron, PeriodicSpecTest). Any other value falls into the default case and produces this error, appended to the job's validation multierror. It protects against typos and unsupported spec types in the job file.

Source

Thrown at nomad/structs/structs.go:5949

	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
		for _, spec := range p.Specs {
			if _, err := cronexpr.Parse(spec); err != nil {
				_ = multierror.Append(&mErr, fmt.Errorf("Invalid cron spec %q: %v", spec, err))
			}
		}

	case PeriodicSpecTest:
		// No-op
	default:
		_ = multierror.Append(&mErr, fmt.Errorf("Unknown periodic specification type %q", p.SpecType))
	}

	return mErr.ErrorOrNil()
}

func (p *PeriodicConfig) Canonicalize() {
	// Load the location
	l, err := time.LoadLocation(p.TimeZone)
	if err != nil {
		p.location = time.UTC
	}

	p.location = l
}

// CronParseNext is a helper that parses the next time for the given expression
// but captures any panic that may occur in the underlying library.
func CronParseNext(fromTime time.Time, spec string) (t time.Time, err error) {

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Set spec_type = "cron" (the only user-facing supported value) in the periodic block.
2. Remove the spec_type field if the default (cron) is desired.
3. Check the Nomad docs/version for the set of valid PeriodicSpec constants.
4. Fix casing — the comparison is exact string equality.

Example fix

// before
periodic {
  spec = "*/5 * * * *"
  spec_type = "Interval"
}
// after
periodic {
  spec = "*/5 * * * *"
  spec_type = "cron"
}

func validSpecType(t string) bool {
    switch t {
    case "", "cron":
        return true
    default:
        return false
    }
}
// call before submitting: if !validSpecType(job.Periodic.SpecType) { ... }

if err := job.Periodic.Validate(); err != nil {
    // surfaces the unknown spec type; correct the field and retry
}

When it happens

Trigger: Submitting a periodic job with `periodic { spec_type = "..." }` set to anything other than "cron" (or the internal test type), e.g. "interval", "Cron" (wrong case), or an empty/misspelled value.

Common situations: Typo in spec_type; assuming other schedule types exist (like systemd timers); copying an old/foreign config format; capitalization mismatches.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Disconnect cannot be configured with both lost_after and sto
• lost_after cannot be a negative duration
• stop_after cannot be a negative duration
• not a valid task schedule state
• numa affinity must be one of none, prefer, or require

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