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.

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"
}
Defensive patterns

Strategy: validation

Validate before calling

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

Prevention

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


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

Appendix: 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)