error-messages

Validation error messages should follow a three-part template: state what's wrong, specify what's expected, and provide a concrete example. For instance, an invalid time delta error reads: "invalid time delta format: +%s. Expected format like +25h, +3d. Example: +1d12h30m". This structure ensures users understand the problem and how to fix it immediately.

Standardized error messages for date and URL validation must include the invalid input, the correct format with multi-line YAML examples where applicable, consistent terminology, and proper quoting rules. This ensures developers and end-users receive actionable guidance and reduces debugging time across the codebase.

Apply a strict template consistently across all validation types—time delta, date, URL, enum, type, and configuration format—covering code validation, runtime checks, and test helpers. Enforce multi-line YAML examples, unified terminology, and quoting conventions. Test message quality to catch inconsistencies early.

Enum and configuration format errors are ambiguous without examples. Including concrete, correct usage patterns in error messages helps users understand valid options and proper syntax immediately, significantly reducing support requests and debugging cycles for configuration-related issues.

Yes. This standardization applies to code validation, runtime checks, test helpers, and migration guidance. The template and formatting guidelines work across all validation contexts, ensuring consistent user experience whether errors surface during development, testing, or production execution.

Type and enum validation errors should use consistent type verbs and clearly enumerate valid options. Pair each error with a concrete example showing correct usage. This approach prevents ambiguity and helps users quickly identify why their input failed and what alternatives are available.