hashicorp/nomad · error

notes must not be longer than 255 characters

Error message

notes must not be longer than 255 characters

What it means

Raised in ServiceCheck.Validate (via validateConsul): the check's free-form Notes field exceeded 255 characters, the maximum length Consul accepts for service check notes.

Source

Thrown at nomad/structs/services.go:461

	} else if sc.SuccessBeforePassing > 0 && !slices.Contains(passFailCheckTypes, sc.Type) {
		return fmt.Errorf("success_before_passing not supported for check of type %q", sc.Type)
	}

	if sc.FailuresBeforeCritical < 0 {
		return fmt.Errorf("failures_before_critical must be non-negative")
	} else if sc.FailuresBeforeCritical > 0 && !slices.Contains(passFailCheckTypes, sc.Type) {
		return fmt.Errorf("failures_before_critical not supported for check of type %q", sc.Type)
	}

	if sc.FailuresBeforeWarning < 0 {
		return fmt.Errorf("failures_before_warning must be non-negative")
	} else if sc.FailuresBeforeWarning > 0 && !slices.Contains(passFailCheckTypes, sc.Type) {
		return fmt.Errorf("failures_before_warning not supported for check of type %q", sc.Type)
	}

	// Arbitrary value, we could bump it if needed
	if len(sc.Notes) > 255 {
		return fmt.Errorf("notes must not be longer than 255 characters")
	}

	return nil
}

// RequiresPort returns whether the service check requires the task has a port.
func (sc *ServiceCheck) RequiresPort() bool {
	switch sc.Type {
	case ServiceCheckGRPC, ServiceCheckHTTP, ServiceCheckTCP:
		return true
	default:
		return false
	}
}

// TriggersRestarts returns true if this check should be watched and trigger a restart
// on failure.
func (sc *ServiceCheck) TriggersRestarts() bool {

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Shorten the notes to 255 characters or fewer
2. Move detailed documentation to an external link and reference it briefly
3. Use a link shortener or config-management reference instead of inline prose

Example fix

// before
check {
  notes = "<a 400-character runbook description>"
}
// after
check {
  notes = "See runbook: https://wiki.example.com/checks/svc"
}

if len(sc.Notes) > 255 {
    return fmt.Errorf("notes must be <= 255 characters (got %d)", len(sc.Notes))
}

When it happens

Trigger: Providing a check block whose Notes string length exceeds 255 runes and validating the service.

Common situations: Pasting long runbook URLs or markdown documentation into check notes; generated notes including large payloads.

Related errors

• expose may only be set for Consul service checks
• on_update may only be set to ignore_warnings for Consul serv
• success_before_passing may only be set for Consul service ch
• failures_before_critical may only be set for Consul service
• failures_before_warning may only be set for Consul service c

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