CF911: Want to modify the CF Step Debugger's use of a random port?

Note: This blog post is from 2010. Some content may be outdated--though not necessarily. Same with links and subsequent comments from myself or others. Corrections are welcome, in the comments. And I may revise the content as necessary.

It's a simple JVM tweak to cause it to use a fixed port:

-DDEBUGGER_SERVER_PORT=portNumber

You can add this either in the "Java & JVM" page of the CF Admin (if in Standard or Enterprise Server), or on the java.args line in the jvm.config file (for any form of CF).

You do need to restart CF for this to take effect.

A few warnings are in order

First, as always, be very careful when changing the jvm configuration. If you make any mistake, then it's possible CF won't be able to restart. (This is one strong reason to favor making changes in the jvm.config file, rather than the "Java & JVM" admin page. If CF can't start, you won't be able to get to the Admin to undo your changes. By knowing how and where to edit the file, you can undo any bad changes.)

Second, beware that you don't pick a port that's already in use, or again CF won't start. And beware that while it may be open now (if you test it), it may not be open later if something's running then that is not now. Along those lines, ....

If you're using multiple instances...

Third, beware especially if you're using the Multiserver form of CF deployment (multiple instances) where by default you have the multiple instances sharing one jvm.config. In that case, they all would inherit this setting, and whichever instance starts first would claim that designated port, and then the others will not be able to start (reporting an error like "FATAL ERROR in native method: JDWP No transports initialized" or "bind failed: Address already in use").

There are various resources that discuss dealing with how to cause each instance to have its own jvm.config (which is a little more challenging when you run CF as a Windows service). See any of these blog entries:

• Nate Williams
• Mark Kruger
• Jeff Houser
• Scott Stroz

Where is this port tweak documented?

I'm sure some may wonder, "where would I have learned of this DEBUGGER_SERVER_PORT tweak for the debugger port?" It's easy to have missed but it's discussed in several places:

• The CFBuilder docs page on using the debugger, also in the whole user guide in PDF form
• Mentioned also in the cf8 release notes (PDF) (the debugger was in fact enabled then, for use with the Adobe CF Eclipse extensions, and is something I've written about before: see older entries in my debugging category here). Sadly, while the CF8 docs do have a page on using the debugger, the page makes no mention of this port setting argument. Worse, I see now that we can no longer add comments to the help pages in that release, to point to the CF9 docs for more.

Want still more documentation on this and more about the debugger?

I also document it in my 25-page chapter on the CF Debugger in the ColdFusion 9 Web Application Construction Kit, Vol 2. Fortunately, that chapter is one of a few that are available online. If I may say so, it's about the only substantial documentation on the CF debugger, as I cover not only understanding and configuring it, but also troubleshooting like that above. (And the concepts apply just as well to CF8.)

Hope all that helps someone.

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