refactor: make client- and operator-facing error messages clearer and actionable

pkg/modules/api/context.go

@@ -111,7 +111,7 @@ func newContext(echoCtx echo.Context, logger *slog.Logger, fs *gotenberg.FileSys
 		if bodyLimit != 0 && newTotal > bodyLimit {
 			return WrapError(
 				fmt.Errorf("body limit reached (> %d)", bodyLimit),
-				NewSentinelHttpError(http.StatusRequestEntityTooLarge, http.StatusText(http.StatusRequestEntityTooLarge)),
+				NewSentinelHttpError(http.StatusRequestEntityTooLarge, "The request body exceeds the configured size limit. Increase it with --api-body-limit, or send a smaller request."),
 			)
 		}
 		return nil

pkg/modules/api/middlewares.go

@@ -43,7 +43,7 @@ func ParseError(err error) (int, string) {
 	}
 
 	if errors.Is(err, context.DeadlineExceeded) {
-		return http.StatusServiceUnavailable, http.StatusText(http.StatusServiceUnavailable)
+		return http.StatusServiceUnavailable, "The request exceeded the time limit. Increase it with --api-timeout, or reduce the workload."
 	}
 
 	if errors.Is(err, gotenberg.ErrFiltered) {
@@ -51,27 +51,27 @@ func ParseError(err error) (int, string) {
 	}
 
 	if errors.Is(err, gotenberg.ErrMaximumQueueSizeExceeded) {
-		return http.StatusTooManyRequests, http.StatusText(http.StatusTooManyRequests)
+		return http.StatusTooManyRequests, "The request queue is full. Retry shortly, or raise the limit with --chromium-max-queue-size or --libreoffice-max-queue-size."
 	}
 
 	if errors.Is(err, gotenberg.ErrPdfSplitModeNotSupported) {
-		return http.StatusBadRequest, "At least one PDF engine cannot process the requested PDF split mode, while others may have failed to split due to different issues"
+		return http.StatusBadRequest, "The requested split mode is not supported, or no PDF engine could process it. Valid modes: 'intervals', 'pages'."
 	}
 
 	if errors.Is(err, gotenberg.ErrPdfFormatNotSupported) {
-		return http.StatusBadRequest, "At least one PDF engine cannot process the requested PDF format, while others may have failed to convert due to different issues"
+		return http.StatusBadRequest, "The requested PDF format is not supported, or no PDF engine could apply it. Valid formats include PDF/A-1b, PDF/A-2b, PDF/A-3b, and PDF/UA."
 	}
 
 	if errors.Is(err, gotenberg.ErrPdfEngineMetadataValueNotSupported) {
-		return http.StatusBadRequest, "At least one PDF engine cannot process the requested metadata, while others may have failed to convert due to different issues"
+		return http.StatusBadRequest, "The requested metadata could not be written; ensure values are valid and free of control characters."
 	}
 
 	if errors.Is(err, gotenberg.ErrPdfStampSourceNotSupported) {
-		return http.StatusBadRequest, "At least one PDF engine cannot process the requested stamp source type, while others may have failed due to different issues"
+		return http.StatusBadRequest, "The requested stamp source is not supported, or no PDF engine could process it. Valid sources: 'text', 'image', 'pdf'."
 	}
 
 	if errors.Is(err, gotenberg.ErrPdfRotateAngleNotSupported) {
-		return http.StatusBadRequest, "At least one PDF engine cannot process the requested rotation angle, while others may have failed due to different issues"
+		return http.StatusBadRequest, "The requested rotation angle is not supported. Valid angles: 90, 180, 270."
 	}
 
 	if invalidArgsError, ok := errors.AsType[*gotenberg.PdfEngineInvalidArgsError](err); ok {

pkg/modules/chromium/chromium.go

@@ -486,12 +486,12 @@ func (mod *Chromium) Provision(ctx *gotenberg.Context) error {
 
 	binPath, ok := os.LookupEnv("CHROMIUM_BIN_PATH")
 	if !ok {
-		return errors.New("CHROMIUM_BIN_PATH environment variable is not set")
+		return errors.New("CHROMIUM_BIN_PATH environment variable is not set; set it to the absolute path of the Chromium or Chrome binary")
 	}
 
 	hyphenDataDirPath, ok := os.LookupEnv("CHROMIUM_HYPHEN_DATA_DIR_PATH")
 	if !ok {
-		return errors.New("CHROMIUM_HYPHEN_DATA_DIR_PATH environment variable is not set")
+		return errors.New("CHROMIUM_HYPHEN_DATA_DIR_PATH environment variable is not set; set it to the absolute path of the Chromium hyphenation data directory (it ships in the Gotenberg image)")
 	}
 
 	mod.args = browserArguments{
@@ -664,12 +664,12 @@ func (mod *Chromium) Validate() error {
 
 	_, err := os.Stat(mod.args.binPath)
 	if os.IsNotExist(err) {
-		return fmt.Errorf("chromium binary path does not exist: %w", err)
+		return fmt.Errorf("Chromium binary does not exist at %q; check the CHROMIUM_BIN_PATH environment variable: %w", mod.args.binPath, err)
 	}
 
 	_, err = os.Stat(mod.args.hyphenDataDirPath)
 	if os.IsNotExist(err) {
-		return fmt.Errorf("chromium hyphen-data directory path does not exist: %w", err)
+		return fmt.Errorf("Chromium hyphenation data directory does not exist at %q; check the CHROMIUM_HYPHEN_DATA_DIR_PATH environment variable (it ships in the Gotenberg image): %w", mod.args.hyphenDataDirPath, err)
 	}
 
 	return nil

pkg/modules/libreoffice/api/api.go

@@ -487,12 +487,12 @@ func (a *Api) Validate() error {
 
 	_, statErr := os.Stat(a.args.binPath)
 	if os.IsNotExist(statErr) {
-		err = errors.Join(err, fmt.Errorf("LibreOffice binary path does not exist: %w", statErr))
+		err = errors.Join(err, fmt.Errorf("LibreOffice binary does not exist at %q; check the LIBREOFFICE_BIN_PATH environment variable: %w", a.args.binPath, statErr))
 	}
 
 	_, statErr = os.Stat(a.args.unoBinPath)
 	if os.IsNotExist(statErr) {
-		err = errors.Join(err, fmt.Errorf("unoconverter binary path does not exist: %w", statErr))
+		err = errors.Join(err, fmt.Errorf("unoconverter binary does not exist at %q; check the UNOCONVERTER_BIN_PATH environment variable: %w", a.args.unoBinPath, statErr))
 	}
 
 	return err

pkg/modules/libreoffice/api/libreoffice.go

@@ -196,7 +196,7 @@ func (p *libreOfficeProcess) Start(logger *slog.Logger) error {
 		select {
 		case err = <-connChan:
 			if err != nil {
-				return fmt.Errorf("LibreOffice socket not available: %w", err)
+				return fmt.Errorf("LibreOffice did not become available within the start timeout; increase --libreoffice-start-timeout or check system resources: %w", err)
 			}
 
 			logger.DebugContext(context.Background(), "LibreOffice socket available")
@@ -204,7 +204,7 @@ func (p *libreOfficeProcess) Start(logger *slog.Logger) error {
 
 			return nil
 		case err = <-waitChan:
-			return fmt.Errorf("LibreOffice process exited: %w", err)
+			return fmt.Errorf("LibreOffice exited unexpectedly during startup; check system resources such as memory, disk, and permissions: %w", err)
 		}
 	}
 }

pkg/modules/libreoffice/routes.go

@@ -400,7 +400,7 @@ func convertRoute(libreOffice libreofficeapi.Uno, engine gotenberg.PdfEngine) ap
 							fmt.Errorf("convert to PDF: %w", err),
 							api.NewSentinelHttpError(
 								http.StatusBadRequest,
-								fmt.Sprintf("A PDF format in '%+v' is not supported", pdfFormats),
+								fmt.Sprintf("The PDF format '%s' is not supported. Valid formats include PDF/A-1b, PDF/A-2b, PDF/A-3b, and PDF/UA.", pdfFormats.PdfA),
 							),
 						)
 					}

pkg/modules/pdfengines/pdfengines.go

@@ -211,7 +211,7 @@ func (mod *PdfEngines) Provision(ctx *gotenberg.Context) error {
 // actually exist.
 func (mod *PdfEngines) Validate() error {
 	if len(mod.engines) == 0 {
-		return errors.New("no PDF engine")
+		return errors.New("no PDF engine is available; enable at least one engine module (e.g. qpdf, pdfcpu, pdftk, libreoffice-pdfengine, exiftool)")
 	}
 
 	availableEngines := make([]string, len(mod.engines))

pkg/modules/qpdf/qpdf.go

@@ -46,7 +46,7 @@ func (engine *QPdf) Descriptor() gotenberg.ModuleDescriptor {
 func (engine *QPdf) Provision(ctx *gotenberg.Context) error {
 	binPath, ok := os.LookupEnv("QPDF_BIN_PATH")
 	if !ok {
-		return errors.New("QPDF_BIN_PATH environment variable is not set")
+		return errors.New("QPDF_BIN_PATH environment variable is not set; set it to the absolute path of the qpdf binary")
 	}
 
 	engine.binPath = binPath