[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.
Do you know what the "var scope problem" is, and how pernicious it can be in causing very subtle bugs that can cause errors that are VERY hard to understand? I list here several resources to help you understand the issue. Some help plainly explain what the issue is, including even a live demo.

I also discuss below the key varscoper tool which you will want to use to help assess and indeed correct your own code.

(Update in 2022, 2019: while the many resources are indeed all quite old now, they all still apply, and most still exist. Where needed, I recovered them from the good ol' archive.org, an awesome resource for finding old content, as I've written about before.)

Why a list was needed

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 created this list 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, and especially when instances of such a CFC may be saved in a shared scope. Like many, these folks still hadn't heard about the problem (introduced in CF6!). Others may have seen mention of it but didn't really understand it.

As always, the CF community has rallied the troops on the matter over the years, and several folks have blogged in various detail or on various related aspects. I think it's helpful to have all the resources in one place. Indeed, I've since moved this also to my "resource lists" page where I keep similar "compendia".

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 (in descending order of recency):

On the new "local" scope added in CF9

Some may know that CF9 added a new "local" scope, to help ease the challenge of working with "unscoped" vars within functions. For more on that, read on:

And some tangential discussions of that, including some compatibility issues with that new "local" scope alternative:

The VarScoper tool

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

The tool: varscoper tool (previously at riaforge.org until mid-2019, then that site was abandoned by Adobe)

It can help with tags or script (though he was seeking help in 2012 with an aspect of working with entirely-script-based CFCs, which never seemed resolved, if that may be an issue for your own needs).

And here are some resources about using that varscoper tool (they will link typically to where it WAS, at riaforge):

Finally, even as old as is, it has continued to be included in or integrated with various tools:


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 from Charlie Arehart: 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
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.

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.
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.
Copyright ©2024 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