# Null Handling in CFML



# Null Support

CFML supports two null handling modes: partial (default) and full. This recipe explains the differences.

Video: [https://www.youtube.com/watch?v=GSlWfLR8Frs](https://www.youtube.com/watch?v=GSlWfLR8Frs)

## Enabling NULL Support

Via **Lucee Server Admin** > **Language/compiler** > **Null support**.

Or per application via [Application.cfc / <cfapplication>](../reference/tags/application.md):

```cfml
this.nullSupport = true;
```

Or toggle dynamically:

```cfml
application action="update" nullsupport="true";
```

## Function Return Values

```cfml
<cfscript>
    function test() {
    }
    dump( test() );

    t = test();
    dump(t);

    dump( isNull( t ) );
    dump( isNull( notexisting ) );
</cfscript>
```

A function with no return value returns `null`. With **partial support**, referencing `t` throws "the key [T] does not exist". With **full support**, `t` is accessible and `isNull(t)` returns `true`.

In both modes, `isNull(notexisting)` safely returns `true` for undefined variables.

## Query Column Values

```cfml
query datasource="test" name="qry" {
    echo("select '' as empty, null as _null");
}
dump( qry );
dump( qry._null );
```

**Partial support**: `qry._null` outputs empty string.
**Full support**: outputs `Empty: null` and `isNull(qry._null)` returns `true`.

## [NullValue()](../reference/functions/nullvalue.md) and the null Keyword

With **partial support**, use [NullValue()](../reference/functions/nullvalue.md) to explicitly return null:

```cfml
var possibleVariable = functionThatMayOrMayNotReturnNull();
return possibleVariable ?: NullValue();
```

With **full support**, use the `null` keyword directly:

```cfml
t = null;
dump( t );
```

## StructKeyExists Behaviour

Key behavioural difference: how [StructKeyExists()](../reference/functions/structkeyexists.md) handles null values.

**Partial support** - null keys are reported as not existing, but they are still stored in the struct:

```cfml
s = { foo: nullValue() };
dump( structKeyExists( s, "foo" ) ); // false
dump( s.keyExists( "foo" ) );        // false
dump( structCount( s ) );            // 1 - the key is still stored
dump( structKeyList( s ) );          // FOO
```

**Full support** - keys set to `null` still exist:

```cfml
s = { foo: null };
dump( structKeyExists( s, "foo" ) ); // true
dump( s.keyExists( "foo" ) );        // true
dump( structCount( s ) );            // 1 - the key exists
dump( isNull( s.foo ) );             // true - but the value is null
```

This distinguishes "key exists with null value" from "key doesn't exist" - important for APIs and database results.

## JSON Serialization

In both modes, a key holding null is serialized as JSON `null`, so a JSON `null` survives a `deserializeJSON()` / `serializeJSON()` round trip.

**Partial support**:

```cfml
s = { name: "John", middleName: nullValue() };
dump( serializeJSON( s ) ); // {"MIDDLENAME":null,"NAME":"John"}
dump( serializeJSON( deserializeJSON( '{"a":null,"b":1}' ) ) ); // {"a":null,"b":1}
```

**Full support**:

```cfml
s = { name: "John", middleName: null };
dump( serializeJSON( s ) ); // {"MIDDLENAME":null,"NAME":"John"}
```

Critical for APIs that expect explicit `null` values rather than missing keys.

## Scoping and isNull()

Always use scoped variable references with [IsNull()](../reference/functions/isnull.md).

When a variable with a `null` value shares a name with another variable in a scope accesssible via scope cascading, `isNull()` can return unexpected results:

```cfml
name = "default";

function greet( name ) {
    if ( isNull( name ) ) {
        writeOutput( "Hello stranger" );
    } else {
        writeOutput( "Hello #name#" );
    }
}

greet( javacast( "null", "" ) );
// Outputs: "Hello default" - found the outer variable, not the null argument!
```

Use scoped references to reliably check for `null`:

```cfml
if ( isNull( arguments.name ) ) { ... }
if ( isNull( local.result ) ) { ... }
if ( isNull( variables.config ) ) { ... }
```

Under default (partial) null support, a null in `local` or `variables` does not stop an unscoped lookup; the search continues through the remaining cascaded scopes. Adobe ColdFusion stops at the nearer-scope null. This is intentional in Lucee. See [Scope Cascading](../guides/developing-with-lucee-server/scope.md) for the behaviour and workarounds (`isNull(local.myVar)`, `this.scopeCascading="strict"`, or `this.nullSupport=true`).

# Categories

[Core CFML Language](../categories/core.md), [Decision logic](../categories/decision.md)

# See Also

[Lucee Syntax](../guides/developing-with-lucee-server.md), [DeserializeJSON()](../reference/functions/deserializejson.md), [IsNull()](../reference/functions/isnull.md), [NullValue()](../reference/functions/nullvalue.md), [SerializeJSON()](../reference/functions/serializejson.md), [StructKeyExists()](../reference/functions/structkeyexists.md), [structKeyExists vs isNull vs ParameterExists vs isDefined vs elvis operator](null-checks-comparison.md), [Null Values in Structs and Arrays](null-structs-and-arrays.md), [Scopes](../guides/developing-with-lucee-server/scope.md), [Application.cfc / <cfapplication>](../reference/tags/application.md)