[Looking for Charlie's main web site?]

The Ultimate Var Scope Resource list? Understanding/resolving problems with the var scope in CFML

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.
If you or anyone you know ever wants to get up to speed on the "var scope problem" in CF, you may be challenged by the fact that there are many discussions of the topic, spread across many blogs. I've accumulated here a starting list of several of the key ones I know of. I certainly may have missed some, so I welcome suggestions of more.

I think it's helpful to have all the resources in one place. Indeed, ultimately I'll move this to my "resource lists" page where I keep similar "compendia".

I created the list of VAR scope resources today after helping a client with a problem which seemed related to this classic problem: the need to remember to var scope your variables in CFCs. It's often the cause of subtle bugs. Like many, they still hadn't heard about the problem (or had seen mention of it but didn't really understand it).

So if you're in that place, or know someone who may be, here are resources to help get started on understanding the topic and related issues. As always, the CF community has rallied the troops on the matter, and several folks have blogged in various detail or on various related aspects.

About the resources

The first few elaborate on the problem, and the first one even includes a live running example to demonstrate the point. Then a couple explain some related issues.

I also then list resources on the related new "local" scope in CF 9, and some more that discuss compatibility issues with that.

Note that these may have been written any time in the past couple/few years, so keep that in mind and be sure to check the comments as well.

The resources

First, some general resources introducing the var scoping issue/feature:

And some that address various issues related to using the VAR scope:

And some on the change in CF9, for the local scope:

And some tangential discussions of that, including some compatibility issues with the new scope:

The VarScope tool

Finally, of course, as most of these resources point out, be sure to use Mike Schierberl's wonderful varscoper tool to help find whether you have instances of this problem. It tells you literally what to change, where, to don't let concern of this problem overwhelm you.


Hope those are helpful. Again, it's just a starting list. I welcome additions, and I look forward to your comments. In time, I'll move this (and any suggested additions) to my "resource lists" page. Check that out for similar lists of resources on various subjects.

For more content like this: Need more help with problems?
  • If you may prefer direct help, rather than digging around here/elsewhere or via comments, I can help via my consulting services
  • See that for more on how I can help a) over the web, safely and securely, b) usually very quickly, c) teaching you as we go, and d) with satisfaction guaranteed
Sami Hoda offered links to additional discussion that he'd raised when CF9 came out, about the potential incompatibility of the new local scope with existing code. Added those links to the last list above. Thanks, Sami.
# Posted By charlie arehart | 3/4/10 8:50 PM

I know this is an older discussion but my company recently moved from CF 8 to CF 10 and we are having issues with the local scope. I know that on CF 8 some people didn't like using <cfset var Local = StructNew() /> but I used it. I've read on a couple of pages that CF 9 will ignore it. Is this documented anywhere in Adobe documentation? If so, is this true in CF 10? I ask because I can't find it anywhere. Also, one of my pages included <cfset var Local = StructNew() /> and another structure <cfset var documentFields = StructNew() /> and CF 10 threw me an error "Variable DOCUMENTFIELDS is undefined." until I changed "<cfset var Local = StructNew() />" to "<cfset var myLocal = StructNew() />" and all of my variables that were prefixed as "Local." to "myLocal." This all leads me to believe that CF 10 is not ignoring <cfset var Local = StructNew() />.
# Posted By scott h | 9/17/12 11:24 AM
No problem, Scott. Old stuff is only old to some. It's new to others. :-)

So as for the local scope, it's not that CF 8 used it and 9/10 do not. Rather, it's that CF9 added a new built-in scope called "the local scope", so when you say you were using it before, what you were doing was creating a variable CALLED local. And now you are experiencing a clash with the new behavior.

As for you saying you "can't find it anywhere" in the CF docs, I would suspect you're looking in the CFML Reference, right? It's such a shame that folks gravitate to that only as "the docs". If you were not aware, there is an equally great (I might even say "better") manual, "Developing Applications with CF" that is in fact nearly as large (1300 pages, versus 1500 for the Ref manual).

You can find the manual online, and in fact here's the link to a discussion of the Local scope:

And here's a link to the section that describes it as a new feature in CF9:


Hope that helps.
# Posted By Charlie Arehart | 9/17/12 11:46 AM
Thanks for the prompt reply and the links to "Developing Applications with CF". I'm happy to see it documented somewhere that CF will ignore variables that are created with the name "Local". Perhaps I don't understand the local scope as well as I should but I think I came across a bug that I am going to file with Adobe

Sorry to repeat myself but I must say that I find it odd that one of my functions in a CFC that included
<cfset var Local = StructNew() />
<cfset var documentFields = StructNew() />
<cfset Local.me = "Scott" />
<cfset StructClear(documentFields) />
<cfset StructInsert(documentFields,"job_id",form.job_id) />

threw this error "Variable DOCUMENTFIELDS is undefined."

And worked after I changed it to
<cfset var myLocal = StructNew() />
<cfset var documentFields = StructNew() />
<cfset myLocal.me = "Scott" />
<cfset StructClear(documentFields) />
<cfset StructInsert(documentFields,"job_id",form.job_id) />

Thanks again
# Posted By scott h | 9/17/12 3:18 PM
Scott, i think you are misunderstanding things somehow. It's not that "CF will ignore variables that are created with the name 'Local'".

It's that local is now a scope all its own, and therefore you run risk of oddities if you try to create a variable that uses that scope as its name (just as one can run afoul in using a variable called URL, when there is a scope of that name, and so on.)

Now, I have not studied the matter carefully, to understand when it may or may not "work', when it may or may not fail with a suitable and obvious message, and when it may or may not result in unexpected behavior (as it seems you're experiencing).

And I won't deny that it could be that the docs could do a better job at discussing those sort of issues. The docs don't always get it right. Sometimes there's more info in release notes (about what's "changing") that may not make it to the docs.

More than that, often it's only after a new release has been out for a while (sometimes weeks, months, or even years) before many people experience a given problem and start talking it up. You may find that others have indeed discussed this more, and may have identified useful workarounds for the challenges, or they may well have opened bug reports to which you could add a vote.

Finally, you may also want to bring this up on the Adobe CF forums (http://forums.adobe....) to see if others have experienced it or would share thoughts.

Hope that's helpful.
# Posted By Charlie Arehart | 9/18/12 4:32 AM
Copyright ©2019 Charlie Arehart
Carehart Logo
BlogCFC was created by Raymond Camden. This blog is running version 5.005.
(Want to validate the html in this page?)

Managed Hosting Services provided by
Managed Dedicated Hosting