yorukot/superfile · error

error generating pdf thumbnail, outputPath: %s : %w

Error message

error generating pdf thumbnail, outputPath: %s : %w

What it means

This error is returned when the pdftoppm child process exits non-zero while rasterizing the first page of a PDF into a JPEG thumbnail. It wraps pdftoppm's stderr, which explains the actual rasterization failure. The output prefix (outputPathWithoutExt) is used because pdftoppm appends the extension itself.

Source

Thrown at src/pkg/file_preview/thumbnail_generator.go:96

	return strings.ToLower(ext) == ".pdf"
}

func (g *pdfGenerator) generateThumbnail(inputPath string, outputPathWithoutExt string) (string, error) {
	outputPath := outputPathWithoutExt + thumbOutputExt
	ctx, cancel := context.WithTimeout(context.Background(), thumbGenerationTimeout)
	defer cancel()

	// pdftoppm -singlefile -png prefixFilename
	pdftoppm := exec.CommandContext(ctx, "pdftoppm",
		"-singlefile",        // output only the first page as image
		"-jpeg",              // Image extension
		inputPath,            // Set input file
		outputPathWithoutExt, // The output prefix. (pdftoppm will add the .jpg ext)
	)

	err := pdftoppm.Run()
	if err != nil {
		return "", fmt.Errorf("error generating pdf thumbnail, outputPath: %s : %w",
			outputPath, err)
	}

	return outputPath, nil
}

type psGenerator struct{}

func newPsGenerator() (*psGenerator, error) {
	if !isGhostscriptInstalled() {
		return nil, errors.New("ghostscript is not installed")
	}

	return &psGenerator{}, nil
}

func (g *psGenerator) supportsExt(ext string) bool {
	extension := strings.ToLower(ext)

View on GitHub (pinned to b72f550bc6)

Solutions

1. Check pdftoppm is installed: `which pdftoppm`; install poppler-utils if absent.
2. Open the PDF in a viewer / run `pdftoppm <file>` manually to confirm the file is valid.
3. If the PDF is encrypted, decrypt or skip thumbnailing for encrypted documents.
4. Verify the output directory exists and is writable.
5. Fall back to a generic PDF icon when generation fails.

Example fix

// before
thumb, err := gen.generateThumbnail(pdfPath)
// after
thumb, err := gen.generateThumbnail(pdfPath)
if err != nil {
    log.Warnf("pdf thumbnail failed: %v", err)
    thumb = defaultPDFIconPath
}

if _, err := exec.LookPath("pdftoppm"); err != nil { return errors.New("poppler-utils not installed") }
if fi, err := os.Stat(pdfPath); err != nil || fi.Size() == 0 { return errors.New("pdf missing or empty") }

thumb, err := gen.generateThumbnail(pdfPath)
if err != nil {
    log.Warnf("pdf thumbnail failed: %v", err)
    thumb = "" // fall back to PDF icon
}

When it happens

Trigger: generateThumbnail invoking pdftoppm on a PDF when poppler-utils is not installed, the PDF is encrypted or corrupt, the PDF uses features pdftoppm can't render, or the output directory for outputPathWithoutExt is not writable.

Common situations: poppler-utils missing in slim Docker images; password-protected PDFs; damaged downloads; PDFs with zero pages; disk-full or permission-denied on the thumbnail cache directory.

Related errors

• error generating video thumbnail, outputPath: %s : %w
• error generating ps thumbnail, outputPath: %s : %w

AI-assisted analysis of yorukot/superfile@b72f550bc6 (2026-09-01). Data as JSON: /api/errors/4e9e4b700e30e736. Report an issue: GitHub.