My experience trying to setup CFwheels 3

[mikegrogan]

Hi All. Long time wheels user. Thank you to the small team that works on this and keeps it going.

We currently have multiple wheels application running as sub folders under the root of our website. All on 2.5. I want to start upgrading them to 3. We use Commandbox locally, and Adobe Coldfusion 2023 on the servers under IIS. We have a decent commandbox setup at this point, but I can't say I'm a Forgebox or package expert.

Since 3 seems like a big update I first just wanted to install a brand new instance to test and see what it looks like. Figured I'd try to do everything through commandbox and the wheels cli. I updated all my installed packages under commandbox to start it off, and thought it looked good.

I was having a lot of problems with wheels new. I quickly realized that the naming changed for the wheels cli. I had to install wheels-cli and unintall cfwheels-cli. After that things went smoothly for the initial creation. I chose ACF 2023 as that is what we currently use.

The info page doesn't seem to convey that it's wheels 3.0.0.+46) the latest one

Project: Wheels Base Template
Project Version: 3.0.0+46
Wheels Version: 3.0.0+46
CFML Engine: Lucee 5.4.8.2

Dependencies

wheels-core @ 3.0.0+46 - Installed: Yes
wirebox @ ^7 - Installed: Yes
testbox @ ^6 - Installed: Yes

Once it was created I tried a server start, but it threw an error regarding the JVM point release number or something. I just took my current server.json settings and updated the javaversion to 17 and that fixed that. Then I ran into another issue that I had fixed before as well regarding bytecode. Frustrating Adobe coldfusion makes us enter these arguments still. There's probably a better workaround, but can't remember.

"jvm":{
"minHeapSize":"1024",
"heapSize":"4096",
"javaVersion":"openjdk17",
"args":[
"-Dcoldfusion.compiler.block.bytecode=false"
]
}

I tried a server start again, but it needed me to cfpm install image, mail, caching, etc. So I did that and then finally got it loaded up!

I clicked through the wheels top navigation (e.g. Info, Routes, API, etc). API and Guides are throwing errors. The rest seem to work.

API and Guides error

Could not find the ColdFusion component or interface tests.Test.
Ensure that the name is correct and that the component or interface exists.

This is under /vendor/wheels/public/docs/core.cfm: line 64

I also see this error

Routines cannot be declared more than once.
The routine $populateDocFunctionMeta has been declared twice in different templates.
 
ColdFusion cannot determine the line of the template that caused this error. This is often caused by an error in the exception handling subsystem.

If I go into vendor\wheels\public\docs\core.cfm and comment out line 64 and do a reload=true I can get the API page to load up.

ArrayAppend(documentScope, {"name" = "test", "scope" = CreateObject("component", "tests.Test")});

If I click on the API page again I then get this error again

Routines cannot be declared more than once.
The routine $populateDocFunctionMeta has been declared twice in different templates.
 
ColdFusion cannot determine the line of the template that caused this error. This is often caused by an error in the exception handling subsystem.

Doing another reload=true and I go back to the "Could not find the ColdFusion component or interface tests.Test." error. This is mostly because I removed my original comment on line 64.

Kind of a loop though. I can only load up the http://localhost/wheels/api page if I comment out "ArrayAppend(documentScope, {"name" = "test", "scope" = CreateObject("component", "tests.Test")});" under core.cfm and call the api page with reload=true every single time.

For the guides page too it's sort of the same thing. I comment out the tests.test and call it with reload=true. From the screenshot below if I select the home guide it errors again, since it's not called with reload=true

I'm sure there's something obvious I might be missing. It just doesn't seem like something is running initially correctly, or I need to tweak something, but not sure what it is at this point.

Wheels cli

Separately I'm trying to learn the wheels cli commands. While many commands seem to work, the wheels server commands don't. I'm on commandbox 6.3.2+00857.

[zainforbjs]

@mikegrogan Thanks for the detailed error message!
I tested the scenario described here locally and wasn’t able to reproduce the issues with the API or the guides. Everything worked as expected on my end.

However, I did encounter the error when using the Wheels CLI. That issue has been fixed in the latest version of the CLI.

Please uninstall the previous version of wheels-cli and install the latest version again(which will now be 3.0.0+47). After updating, the problem should be resolved.

[mikegrogan]

Hi @zainforbjs thanks for the reply. I updated and wheels server commands are working now! Thanks for that.

In reviewing so far wheels server start adds this to my server.json file at the end, which doesn't seem to be correct.

"openbrowser=true":true,
"host=127.0.0.1":true

I already have these in my server.json as well.
"openBrowser":true,
"web":{
"host":"localhost",
..
}

API and Guides error

I changed my coldfusion server from ACF 2023 to ACF 2025 and still get the same error when trying to load this part of the wheels internal site.

To be complete I just tried with the latest version of Lucee and it worked! I think you have an adobe coldfusion bug. Maybe test on that to re-create the issue. Assuming you ran on Lucee. I'd love to help (time permitting), but not sure I completely understand the issue yet.

[zainforbjs]

@mikegrogan Thanks for the detailed feedback and for testing on both ACF and Lucee.

I was able to reproduce the issues you described. The problems related to the wheels server commands have now been fixed in wheels-cli, and the error affecting the API pages in the internal site has also been resolved.

The Guides page issue may still remain for the moment, but the main issues reported in this thread should now be addressed.

Please make sure you are using the latest version of Wheels and reinstall/update wheels-cli to the latest version to get the fixes.

[mikegrogan]

Wheels server start looks good! Thanks.

I'm using ACF 2023@latest for all the information below:

Jdk casting issue

I must have done something. After upgrading wheels-core and wheels-cli to 3.0.0+48 it wouldn't start. I deleted the directory and started over. Maybe this is my configuration as well, but I always get this error and have to update the server.json.

server start
× | Starting Server
|------------------------------
| You're using a custom Tuckey rewrites file (deprecated). This will put CommandBox
| in 'legacy' mode where static files will bypass the Resource handler and all be ser
| ved by the servle
|------------------------------
| × | Installing package [java:jdk-11.0.16.1:lockVersion]
| | > can't cast [jdk-11.0.16.1] string to a number value
| |------------------------------------------------------------------

ERROR (6.3.2+00857)
can't cast [jdk-11.0.16.1] string to a number value

Solution

I add something like this in server.json and it works

"jvm": {
		"minHeapSize": "1024",
		"heapSize": "4096",
		"javaVersion": "openjdk17",
		"args": [
			"-Dcoldfusion.compiler.block.bytecode=false"
		]
	}

I also had to do server forget [name] or I was running into other issue. Just for anyone else that was having issues like me.

Onserverinitialinstall

Just a suggestion. It might be helpful to add something like this to the server.json file by default, so the first thing we are greeted with is package not installed. This is for ACF at least.

"scripts": {
		"onServerInitialInstall": "cfpm install chart,caching,debugger,document,feed,ftp,htmltopdf,image,mail,oracle,pdf,print,scheduler,spreadsheet,zip"
	},

Url rewriting in Commandbox6+

Also, as started in the logs urlrewrite.xml is depreciated by commandbox 6+. I've updated my setup to add something like this

"rulesFile":"../config/urlrewriting/rules.txt"

and rules.txt looks something like this below. Just a suggestion again for going forward with commandbox.

### rules.txt
regex( pattern='^/(.*)$', case-sensitive=false ) -> {

    # Check for static assets (also case-insensitive)
    not regex( pattern='^/(?:flex2gateway|jrunscripts|cfide|cf_scripts|cfformgateway|cffileservlet|lucee|files|images|javascripts|miscellaneous|stylesheets|wheels/public/assets|robots.txt|favicon.ico|sitemap.xml|rewrite.cfm)', case-sensitive=false ) -> {
        
        # Rewrite to the rewrite.cfm inside the captured subfolder
        rewrite( '/${1}/rewrite.cfm/${2}' );
        done;
    }
}

New experience on 3.0.0+48

API

The API page initially didn't load fully (http://127.0.0.1:57250/wheels/api). Something about twelvehour, etc.. I wish I got a screenshot. Either way, I navigated away and then back and it loaded. I just forgot the server again and started over and it worked the first time. Nice!

Guides

As mentioned guides still doesn't work fully.

On initial page load I see

If I refresh the page I then see this.

Tests

If I click through the pages I eventually see this on the tests pages too. The page loaded the initial time. If I click on any of the tests (2nd load) it'll trigger this too. Just can't load the tests section more than one.

[zainforbjs]

@mikegrogan Thanks for taking the time to test everything so thoroughly and for sharing your findings.

Regarding the Guides and Tests sections of the internal site: I was able to reproduce the issues you described and they have now been fixed. These fixes are included in the latest updates, so after updating to the most recent versions of Wheels and wheels-cli, those pages should load and behave correctly.

For the JDK casting issue, this appears to be related to Adobe ColdFusion/CommandBox rather than Wheels itself. The error occurs when CommandBox attempts to process the jdk-11.0.16.1 package version and incorrectly tries to cast part of the value as a number. Your workaround of explicitly setting the javaVersion in server.json (for example openjdk17) is a good approach and should prevent that problem. We'll keep an eye on this, but at the moment it seems to be outside the scope of Wheels.

Thanks as well for the suggestions around improving the default setup. The idea of adding an onServerInitialInstall script to install the common ACF packages is a good one, and we’ll definitely consider incorporating something like that into the default server.json configuration in the future to improve the initial developer experience.

Your note about CommandBox 6+ deprecating urlrewrite.xml is also appreciated. Moving toward the rulesFile configuration and a rules.txt setup is something we’ll review as part of improving compatibility with newer CommandBox versions. We’ll also take a closer look at the other configuration details you mentioned to see if there are additional improvements we can make.

Thanks again for testing and for the detailed feedback — it’s very helpful for improving the 3.0 release. If you run into any other issues or have further suggestions, please feel free to share them.

[mikegrogan]

@zainforbjs Things are looking good and thanks for all your hard work. The last thing I'm noticing for the internal wheels pages is I can load tests the first time, and then when I load it a second time this still shows up. The API and Guides pages work nicely now!

[zainforbjs]

@mikegrogan Thanks for the update and for continuing to test this.

I just ran another round of testing on my side to try and reproduce the issue with the Tests page loading the second time. To make sure the environment was clean, I created a completely fresh application using the wheels new command, selected the stable version of Wheels, and chose Adobe ColdFusion 2023.

After the app was generated, I configured the datasource, started the server, and then went through the internal Wheels pages. I tested the API, Guides, and Tests sections multiple times and was not able to reproduce the error. All pages loaded correctly, including reloading the Tests section.

Can you test it again with a fresh install of wheels to verify?

[mikegrogan]

I upgraded to 3.0.0+49 from +48 and it works now! Thank you so much for working through all of that.

Now the real work begins migrating our various wheels app to 3.

[zainforbjs]

We’re glad to hear that the issue has been resolved. We’re also excited to share that more updates are coming soon in the upcoming v3.1.0 release.