ColdFusion has three distinct PDF mechanisms, and picking the right one depends entirely on the actual job: generating a brand new PDF from HTML/CFML (cfhtmltopdf or cfdocument), or manipulating a PDF that already exists (cfpdf), merging, watermarking, protecting, extracting.
Learning Objectives
After completing this lesson, you'll be able to:
- Choose between cfhtmltopdf, cfdocument, and cfpdf for a given task.
- Explain why cfhtmltopdf is Adobe-only, and what Lucee uses instead.
- Recognize that Adobe's PDF generation runs as a separate managed service, not just a tag.
Three Mechanisms, Three Jobs
Need a PDF
Generating New Content, or Editing an Existing PDF?
cfhtmltopdf / cfdocument, or cfpdf
Output PDF
The Three Mechanisms
| Tag | Job | Availability |
|---|---|---|
| cfhtmltopdf | Generates a new PDF from HTML/CSS/JS, using a modern WebKit-based engine (PDFG) | Adobe ColdFusion only |
| cfdocument | Generates a new PDF (or FlashPaper) from CFML/HTML between its tags | Adobe ColdFusion and Lucee (a different rendering engine underneath on each) |
| cfpdf | Manipulates a PDF that already exists: merge, split, watermark, protect, extract text/images | Adobe ColdFusion and Lucee (with real differences in which actions are implemented) |
cfdocument is the one tag that runs on both engines, which makes it the right default when the exact same code needs to generate PDFs on Adobe and Lucee alike.
Adobe's PDF Service: A Separate Managed Process
cfhtmltopdf isn't just a tag, it's backed by a PDF Service Manager, a Jetty-based process running the WebKit engine (PDFG) separately from the main ColdFusion server. It's configured in the Administrator under Data & Services > PDF Service, with pool settings like minService/maxService (how many conversion processes run concurrently) and waitingQueueSize (how many conversions can queue up).
On Linux, this service has real system-level dependencies: 32-bit glibc, zlib, libX11, and expat, plus IBM Type1 fonts installed separately into /usr/share/fonts. Skipping these is a genuine, common cause of PDF generation failing only in a Linux deployment.
Lucee's Rendering Engines: Classic vs Flying Saucer
| Engine | Characteristics |
|---|---|
| Flying Saucer (modern, default) | Full CSS 2.1 support, smaller output files, lower memory/CPU use, actively maintained |
| Classic (PD4ML-based, legacy) | Older rendering, kept for exact visual compatibility with documents built against it |
The two engines don't necessarily produce pixel-identical output for the same input, a real consideration when migrating an existing cfdocument-based PDF from the classic engine to Flying Saucer.
Common Beginner Mistakes
Assuming cfhtmltopdf exists on Lucee
It doesn't, it's Adobe-only. Lucee generates PDFs from HTML/CFML through cfdocument and its own Flying Saucer or classic engine instead.
Leaving PDF service debug logging enabled long-term in production
Adobe's own documentation warns against this specifically, due to the performance impact of extended logging.
Assuming cfpdf is the tool for generating a new PDF from HTML
cfpdf operates on PDFs that already exist, merging, watermarking, protecting, and similar. Generating new content from HTML is cfhtmltopdf or cfdocument's job.
Best Practices
- Use cfhtmltopdf for modern HTML5/CSS3 content when the code only needs to run on Adobe ColdFusion.
- Use cfdocument when the exact same code needs to generate PDFs on both Adobe ColdFusion and Lucee.
- Reserve cfpdf for operating on a PDF that already exists, not for generating new content.
- Verify Linux system dependencies (glibc, zlib, libX11, expat, IBM Type1 fonts) before deploying PDF generation to a Linux server.
Interview Questions
Why would cfhtmltopdf-based code fail to run on Lucee at all?
cfhtmltopdf is Adobe ColdFusion-only, Lucee has no equivalent tag by that name. cfdocument is the cross-engine option for generating a PDF from HTML/CFML on both.
What's the difference between what cfdocument and cfpdf are each used for?
cfdocument generates a new PDF (or FlashPaper) from CFML/HTML content. cfpdf manipulates a PDF that already exists, merging, watermarking, protecting, extracting content, rather than generating new content from scratch.
Why might a PDF that renders fine on Lucee's classic engine look different after switching to Flying Saucer?
They're genuinely different rendering engines, Flying Saucer offers full CSS 2.1 support and smaller output but isn't guaranteed to produce visually identical output to the older PD4ML-based classic engine.
Summary
In this lesson, you covered ColdFusion's three distinct PDF mechanisms, cfhtmltopdf and cfdocument for generating new content, cfpdf for manipulating existing PDFs, why cfhtmltopdf is Adobe-only, and the real difference between Lucee's classic and Flying Saucer rendering engines.
What's Next?
The next lesson covers cfhtmltopdf itself in depth: its attributes, page setup, and security options.