Follow-up on CF 2021 update 15: understanding, solving packages unexpectedly removed

If you've recently applied CF2021 update 15 or are planning to, you need to be aware of a known issue which can cause unexpected removal of some CF packages (modules) which occurs upon the CF restart after installing the update: specifically it's the document, htmltopdf, pdf, presentation, print, and report modules. The good news is that these are easily added back, either using the CF Admin or via the cfpm command-line tool (added in CF2021).

In this post, I discuss this issue, those options for adding them back, and I also share how I'd found the underlying root cause of the problem: the update has a mistaken internal indication that these packages were updated in this update, when they were not. I'm hoping that Adobe may soon be fixing the problem by creating a new update file, to at least benefit those doing this update going forward. I'll share also the bug report for that (and another on a related matter, about installing multiple packages via cfpm).

TLDR

If you just want to "solve the problem" caused in applying this update 15, simply go into the CF Admin and its "Package Manager" page, go to its "Available Packages" section, and click each of those to install them. (Couldn't you also click the "Install All" button offered there? Yes, but there are reasons to be careful about that. Couldn't you use the cfpm tool? Again, yes. I will address both these points and more, below.)

Background

For context, I'll remind readers that I had posted an announcement on Aug 20, they day the updates were released for CF2023 (update 9) and 2021 (update 15). Within a couple of days, folks started reporting in the comments there that they were encountering this problem.

Some wouldn't even notice the problem (I had not, at first), because unless you're watching the CF logs closely, you're only indication would be if someone either a) ran CFML code which was reliant on one of the now-missing packages or b) someone visited a page in the CF admin related to the package.

Anyway, the problem was reported to Adobe who have for now at least added a "known issue" section near the top of the update technote for CF2021 update 15, where they discuss only very briefly how these 6 packages are mistakenly removed and need to be added back.

What IS the problem with package management in this update

The nominal problem in this update is that (unlike CF2023 update 9 released the same day), update 15 of CF2021 mistakenly has an internal indication that there are packages that were updated as of update 15 (those packages listed above, document, htmltopdf, pdf, presentation, print, and report)...but there are in fact NO package updates in this CF update. And as I'll explain below, these packages end up being uninstalled on the next startup after the update...but they are not reinstalled.

As for the root cause of the problem, that's something I determined once people started bringing up the issue in the comments on my post from Aug 20: I found that there was a file buried deep (DEEP) within the update jar (which is what underlies all CF updates), and that was mistakenly telling the update that there were package updates for this update 15 (when there are in fact none introduced with this update--though you may find some happen if you are skipping to this from an older CF update).

For more details, you can either read the comments there (especially mine starting on Aug 23) or see the Adobe tracker ticket (CF-4223435) that was subsequently created for this issue and where I repeated the key details of the root cause problem.

How can you find that the problem happened to you?

So moving on, there are a couple of ways you can confirm the problem has happened for you (it pretty much is happening to anyone applying the update--unless they for some reason already were not implementing those 6 packages above).

First, the most obvious clue would be that if you visit the CF Admin "Package Manager" page, its last section called "Available Packages" will indicate, "These packages are not yet installed on the system". And if you click to expand that section, you would see at least those 6 packages listed above (document, htmltopdf, pdf, presentation, print, and report. And to be clear, you may well see still other uninstalled packages, if someone simply opted not to install those, of course.)

Second, you can find clear evidence of the problem in the CF startup logs, specifically coldfusion-out.log, on the first restart after the update was applied. But let me take a diversion to share more about the logging of package updates, as I find it's something few are aware of.

How CF logs the process of detecting and installing package updates

If you didn't know, when any CF update incorporates package updates, that will be tracked first at the bottom of the update log. (I have a blog post talking about how to find the update log for each update you attempt to apply. That focuses more on watching out for errors, which appear near the top of the log. And ever since CF2021, now that same log will list near the bottom whether the update incorporates any package updates.

Then when CF restarts (after the update is applied), it's during that startup that CF will first uninstall any packages "to be updated" (and log that), and then it would proceed to implement the updated packages (and log that)...but again in this case will not find any packages updated by update 15. (Again, if you may be skipping to update 15 from earlier updates, then you MAY see in the log that CF DOES successfully implement some other package updates from those earlier CF updates.)

Solving the problem: via the CF Admin

So with all that preface out of the way, how can you solve the problem. As I noted in the TLDR, the simplest solution is to go into the CF Admin and its "Package Manager" page, go to its "Available Packages" section, and click each of the six named here to install them (assuming you want all 6 of them).

Note that installing these packages does NOT require that CF be restarted: the package updates simply take effect immediately. Any Admin or app pages that were failing because of this should now "just work". Yay.

FWIW, you could indeed just click the "Install All" button, to do them all at once rather than one at a time...at least long as the ONLY uninstalled packages listed there were those 6 (document, htmltopdf, pdf, presentation, print, and report). Do beware that if there are OTHER packages listed there, those may have been uninstalled intentionally by someone in the past, and if you did "install all" you'd be adding them back--which may not be what you or someone there wants to have happen.

Solving the problem: via the cfpm CLI tool

Finally, I appreciate that some may find it tedious to do this re-installing of the packages using the CF Admin (whether clicking one of several buttons). I love reminding people that starting with CF2021 (when the whole packagee/module feature was introduced), Adobe also added a command line tool called cfpm.

It can be used to manage packages, including listing them, installing or uninstalling them, updating them, and even scanning your code base to find what packages are needed by your code! (And if you're new to using CFPM and wish to learn more, besides the substantial CF docs on it, I also did an entire presentation introducing its many facets. See the PDF or youtube video link as well as the description at my presentations page.)

Anyway, you can implement the packages via the cfpm, which is found in your CF instance's bin folder, such as c:\coldfusion2021\cfusion\bin. As discusse in the resources above, you can either run the tool "interactively" (type or run "cfpm", which opens an interactive CLI where you can enter its commands) or "imperatively" (typing "cfpm [command]"). As such you can run the cfpm to install these packages using either of a few approaches:

• you could enter the cli interactively and then use
  install document, htmltopdf, pdf, presentation, print, report
• you could enter the cli interactively and then use
  install all
  (though as I noted above that may implement other packages that were previously and intentionally left uninstalled)
• or you could use the cfpm imperatively, such as
  cfpm install all
  or
  cfpm install document,htmltopdf,pdf,presentation,print,report

If you may opt to do that imperative cfpm as I show above, note that there is currently a bug (in CF2021 and 2023) where you must NOT enter any spaces after the commas when listing multiple packages to install (or uninstall). Let me elaborate a bit more on that before we conclude.

Bug related to installing multiple packages via "imperative" use of cfpm

As I was putting together the info that I shared (with Adobe and the community, in my Aug 23 blog comments and in that tacker ticket), I discovered that if I tried to use the cfpm imperatively with this code:

, the command failed. That would work find INTERACTIVELY (as I show above), but when run imperatively (outside of the cfpm cli) it would fail, reporting "Invalid command. You have passed more parameters than required."

So I created a bug report for that (a href="https://tracker.adobe.com/#/view/CF-4223452">CF-4223452). And Adobe has told me they're working on fixing that one. While it's not DIRECTLY related to the issue discussed in this post, it is indeed indirectly related, so I wanted to share this news here. As with the bug created for this issue, if you want to add a vote to the tracker tickets, that helps Adobe pay closer attention to the matter.

Conclusion

So phew, another long-ish post. Again, the TLDR shows that the solution is simple (install the packages that were mistakenly uninstalled). But I wanted to show both that there were multiple ways to do that (with pros and cons, and their own issues), and I wanted to explain WHY the problem happened (and my discovery of the root cause)...and my hope that Adobe will ultimately just "update the update" to make this problem go away.

Until then, I hope this was helpful. Comments welcome. And as always, if you need help doing this or anything related to troubleshooting CF, that's what I do for a living, via short-term screenshare consulting. More at carehart.org/consulting.

For more content like this from Charlie Arehart:

• Signup to get his blog posts by email:
• Follow his blog RSS feed
• View the rest of his blog posts
• View his blog posts on the Adobe CF portal

Need more help with problems?

• If you may prefer direct help, rather than digging around here/elsewhere or via comments, he can help via his online consulting services
• See that page for more on how he can help a) over the web, safely and securely, b) usually very quickly, c) teaching you along the way, and d) with satisfaction guaranteed