← Back to ColdFusion Administrator Reference

Extensions - CFX Tags

Register and manage CFX custom tags built in C++ or Java

Last updated: October 27, 20258 min read

Overview

CFX (ColdFusion Extension) tags allow you to extend ColdFusion functionality by writing custom tags in C++ or Java. These tags integrate directly with the ColdFusion runtime and can perform operations that require access to native system resources, third-party libraries, or performance-critical processing that benefits from compiled code.

Modern Alternatives: Before implementing CFX tags, consider modern alternatives like Java integration via JavaLoader, native CFML components, or REST API integration. CFX tags are a legacy feature primarily maintained for backward compatibility.

CFX Tag Types

ColdFusion supports two types of CFX tags with different implementation approaches.

Java CFX Tags

PurposeCustom tags implemented as Java classes
ImplementationJava class implementing com.allaire.cfx.CustomTag interface
PerformanceRuns in the same JVM as ColdFusion, good performance
RecommendationPreferred over C++ CFX for easier development and deployment
Advantages:
  • Platform-independent (works on Windows, Linux, macOS)
  • No compilation needed for deployment
  • Access to all Java libraries and APIs
  • Easier to debug and maintain
  • No separate process management

C++ CFX Tags

PurposeCustom tags implemented as native C++ libraries (DLL/SO)
ImplementationC++ code using ColdFusion CFX API, compiled to native library
PerformancePotentially faster for CPU-intensive operations
RecommendationUse only when Java CFX is insufficient
Limitations: Platform-dependent, requires compilation for each OS, harder to debug, potential stability issues if code crashes. C++ CFX tags are largely obsolete in modern ColdFusion development.

Registering CFX Tags

Configure CFX tags in the ColdFusion Administrator to make them available to your applications.

Tag Name

PurposeName used to invoke the tag in CFML code
FormatMust start with cfx_ prefix
Examplecfx_ImageResize, cfx_SendSMS
Naming Convention: Use descriptive names that indicate the tag's purpose. Case is preserved but tags are case-insensitive when invoked.

Tag Type

OptionsJava or C++
ImpactDetermines how ColdFusion loads and executes the tag

Java Class Path (Java CFX)

PurposeFully qualified Java class name implementing the CFX tag
Formatcom.company.package.ClassName
Examplecom.example.cfx.ImageProcessor
Class Requirements:
  • Must implement com.allaire.cfx.CustomTag interface
  • JAR file must be in ColdFusion classpath
  • Place JAR in {cf-home}/lib or add to Java classpath
  • Requires ColdFusion restart after adding new JARs

Library Path (C++ CFX)

PurposeFull path to the compiled library file
WindowsC:\cfx\mytag.dll
Linux/Unix/opt/cfx/mytag.so
Important: The library must be compiled for the specific operating system and architecture running ColdFusion. 64-bit ColdFusion requires 64-bit libraries.

Procedure (C++ CFX)

PurposeName of the exported function in the C++ library
DefaultProcessTagRequest
Note: Most C++ CFX tags use the default procedure name. Only change if your library exports a different function name.

Keep Library Loaded

PurposeKeep C++ library in memory between calls
DefaultDisabled
RecommendationEnable for frequently used tags to improve performance
Trade-off: Keeping the library loaded improves performance but increases memory usage. Enable for production tags that are called frequently.

Description

PurposeDocumentation describing the tag's functionality
RecommendationInclude purpose, required attributes, and usage notes

Using CFX Tags

Once registered, CFX tags can be invoked like any other ColdFusion tag:

Using CFX Tags in CFML
<!--- Call a Java CFX tag --->
<cfx_ImageResize
  source="/images/photo.jpg"
  destination="/images/photo_thumb.jpg"
  width="200"
  height="150">

<!--- Call with return values --->
<cfx_ProcessData
  inputData="#myData#"
  outputVar="result">

<cfoutput>#result#</cfoutput>
<!--- Wrap CFX tag calls in error handling --->
<cftry>
  <cfx_ImageResize
    source="#filePath#"
    destination="#thumbnailPath#"
    width="200"
    height="150">

  <cfcatch type="any">
    <cflog
      file="cfx-errors"
      type="error"
      text="CFX tag error: #cfcatch.message#">

    <!--- Fallback behavior --->
    <cfset useDefaultImage()>
  </cfcatch>
</cftry>

Development Guidelines

Java CFX Development

Best Practices:
  • Thread Safety: Ensure your implementation is thread-safe (one instance serves all requests)
  • Error Handling: Throw clear exceptions with helpful error messages
  • Validation: Validate all required attributes and provide defaults
  • Documentation: Document all attributes, return values, and usage examples
  • Testing: Test thoroughly with various input combinations
  • Logging: Use ColdFusion logging for debugging and error tracking

Security Considerations

Security:
  • Input Validation: Always validate and sanitize user input
  • File System Access: Restrict file operations to allowed directories
  • Sandboxing: CFX tags bypass ColdFusion sandbox security
  • Resource Limits: Implement timeouts and resource limits
  • Privilege Management: Run with minimum required privileges

Common Issues & Solutions

CFX Tag Not Found

Symptom: Error message "CFX tag is not registered" when calling the tag
Solutions:
  • Verify tag is registered in ColdFusion Administrator
  • Check tag name includes cfx_ prefix
  • Verify case-sensitive class name matches exactly
  • For Java CFX: Ensure JAR is in classpath and ColdFusion restarted
  • For C++ CFX: Verify library path is correct and file exists

ClassNotFoundException (Java CFX)

Symptom: Java ClassNotFoundException when invoking the tag
Solutions:
  • Verify JAR file is in ColdFusion classpath ({cf-home}/lib)
  • Check fully qualified class name is correct
  • Ensure JAR contains the specified class (verify with jar tf)
  • Restart ColdFusion after adding/updating JAR files
  • Check for package name mismatches

Library Load Failed (C++ CFX)

Symptom: Unable to load C++ library, error loading DLL/SO file
Solutions:
  • Verify library is compiled for correct platform (Windows/Linux) and architecture (32/64-bit)
  • Check file permissions (library must be readable by ColdFusion process)
  • Ensure all dependent libraries are available
  • On Linux: Check library dependencies with ldd command
  • Verify library exports required functions

CFX Tag Execution Errors

Symptom: Tag registered but fails during execution with runtime errors
Solutions:
  • Check ColdFusion logs for detailed error messages
  • Verify all required attributes are provided
  • Test tag with minimal inputs to isolate issue
  • Add logging to tag implementation for debugging
  • Check for thread safety issues if errors are intermittent
  • Verify tag has access to required resources (files, network, etc.)

Related Resources

Server Settings - Java & JVMConfigure Java classpath and JVM settings for CFX tagsSecurity - Sandbox SecurityUnderstand how CFX tags interact with security sandboxesColdFusion Administrator ReferenceComplete administrator guide and settings reference