Migration - Upgrades

How to Fix Broken Links After ColdFusion Migration

by Aaron Longnion
11 min read
Contents show

Why this Migration or upgrade matters

Upgrading or migrating a ColdFusion application—whether moving between Adobe ColdFusion versions, switching to Lucee, changing operating systems, or replacing IIS/Apache—often alters URL handling, mappings, and rewrite behavior. Those changes can cause Broken links, 404 errors, and lost SEO equity. Fixing links quickly preserves traffic, conversions, and API consumers, and it stabilizes your Deployment by aligning ColdFusion mappings, web server connectors, and URL rewriting rules.

Prerequisites / Before You Start

Before you fix Broken links, set yourself up for success with a clear plan and a complete inventory.

  • Backups and snapshots
    • Full backup of application code (including /cfcs, /includes, /views).
    • Database snapshot/backups (for dynamic URL generation).
    • Web server and ColdFusion Configuration exports (IIS config, Apache vhost/.conf files, ColdFusion Administrator settings).
    • Backup of prior URL rewrite rules (IIS URL Rewrite, Apache mod_rewrite).
  • Versions and environment
    • Source and target ColdFusion engines and versions (e.g., Adobe ColdFusion 11/2016/2018/2021/2023, Lucee 5+).
    • Java and Tomcat versions bundled with ColdFusion or Lucee.
    • Operating system (Windows vs Linux) and its filesystem case sensitivity.
    • Web server: IIS 10, Apache 2.4, Nginx (fronted to Tomcat via AJP/BonCode or proxy).
  • Connectors and modules
    • Confirm ColdFusion web server connector is installed and updated (wsconfig for Adobe CF).
    • IIS URL Rewrite module installed; Apache mod_rewrite or proxy_ajp enabled.
    • Confirm which file extensions are handled by the connector (.cfm, .cfc, .cfm/* for REST).
  • URL structure knowledge
    • Historical sitemaps and canonical URL patterns (with/without .cfm, trailing slash policy).
    • Known inbound links from Marketing campaigns and third-party sites.
    • Old-to-new path mapping (if your Migration changed directories or routes).
  • Code-level dependencies
    • Use of Application.cfc (this.mappings, onRequestStart, onMissingTemplate).
    • CFML helpers that generate URLs (e.g., centralized link builders).
    • Hard-coded relative vs absolute links in templates and emails.
  • Environments for safe validation
    • A staging environment mirroring production rewrite rules and connectors.
    • Ability to test SSL, HTTP to HTTPS redirects, and canonical www/non-www settings.

A quick inventory table you can fill out:

Area Source Target Notes
ColdFusion Engine e.g., ACF 2018 ACF 2023 Check deprecated functions and settings
OS Windows Ubuntu Case sensitivity change affects URLs
Web Server IIS 10 IIS 10 Same; module versions may differ
Connector ISAPI ISAPI Reinstall/update connector Post-upgrade
URL Pattern /products.cfm?id= /products/{id} Requires 301 redirects
Extensions .cfm visible Extensionless Requires rewrite and handler mapping
See also  How to Handle ORM Schema Changes in Migration

Step-by-step guide to fix broken links after a ColdFusion migration

1) Crawl and Audit your existing URLs

  • Generate a full list of live links from:
    • Existing XML sitemaps.
    • Web analytics (top landing pages and 404 reports).
    • A site crawler or link checker.

Examples:

  • wget (Linux/Mac):

    wget –spider -r -nd -nv -o spider.log https://www.example.com/
    grep -E “broken link|404|500” spider.log

  • PowerShell (Windows) quick probe:

    $urls = Get-Content .\urls.txt
    foreach($u in $urls){ try{ $r=Invoke-WebRequest -Uri $u -Method Head -UseBasicParsing;
    “$($r.StatusCode) $u” } catch { “ERR $u” } }

Export this inventory to map old-to-new paths.

2) Freeze changes and back up configurations

  • Code freeze to prevent new links being introduced mid-migration.
  • Export IIS site Configuration or Apache vhost files.
  • Export ColdFusion Administrator settings and data sources.
  • Tag the repo and archive static assets.

3) Recreate ColdFusion mappings and per-application settings

Broken links often stem from missing CF mappings that change relative paths in includes and links.

  • In ColdFusion Administrator, re-add server-level mappings previously configured.
  • Prefer per-application mappings in Application.cfc for portability:

component {
this.name = “MyApp”;
this.mappings = {
“/views” = expandPath(“/app/views”),
“/controllers” = expandPath(“/app/controllers”),
“/assets” = expandPath(“/public/assets”)
};
this.sessionManagement = true;
this.invokeImplicitAccessor = true;
}

  • Verify that includes and generated links reference mapped paths (e.g., href=”/assets/css/site.css”).

4) Reinstall and validate the web server connector

If the connector is misconfigured, .cfm/.cfc requests may fall through and produce 404s.

  • Adobe CF: run wsconfig to reinstall/update the connector for each website.
  • IIS:
    • Confirm Handler Mappings route .cfm and .cfc to the ColdFusion ISAPI module.
    • Confirm “Invoke handler only if request is mapped” is correctly set for your rules.
  • Apache:
    • Ensure mod_rewrite and proxy/ajp modules are enabled.
    • Confirm that .cfm/.cfc requests reach Tomcat.

Sanity test:

5) Port and test URL rewrite rules

Many broken links arise because rewrite rules changed Syntax or were not migrated.

  • IIS URL Rewrite example (redirect .cfm to extensionless, keep query string):

  • Apache .htaccess example:

    RewriteEngine On

    Redirect visible .cfm to clean URLs

    RewriteRule ^(.+).cfm$ /$1 [R=301,L]

    Route clean URLs to underlying .cfm

    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteCond %{REQUESTFILENAME} !-d
    RewriteRule ^([a-z0-9/    -]+)$ $1.cfm [QSA,L]

  • Maintain canonical domain and HTTPS redirects before app rewrites:

    • Redirect http->https.
    • Redirect non-www->www or vice versa.
    • Avoid redirect chains by ordering rules carefully.

6) Normalize case sensitivity and file extensions

Moving from Windows to Linux can break links due to case differences.

  • Standardize file names and URL references to lowercase or a consistent scheme.
  • If you changed extension policy (e.g., removed .cfm), implement 301 redirects from old to new.

7) Implement a durable 301 redirect strategy

For paths that truly changed, add explicit, permanent redirects. Use rewrite maps for large sets.

  • IIS rewrite map:

  • Apache map:

    RewriteMap legacymap txt:/etc/apache2/legacy_map.txt
    RewriteCond ${legacymap:%{REQUEST_URI}?%{QUERY_STRING}|NOT_FOUND} !NOT_FOUND
    RewriteRule ^ %{legacymap:%{REQUEST_URI}?%{QUERY_STRING}} [R=301,L]

    legacy_map.txt:

    /products.cfm?id=100 /products/100
    /aboutus.cfm /about

  • CFML fallback using onMissingTemplate for logging and emergency redirects:

    public void function onMissingTemplate(required string targetPage){
    // Simple pattern mapping
    if (targetPage EQ “aboutus.cfm”){
    cfheader(statuscode=301, statustext=”Moved Permanently”);
    cflocation(url=”/about”, addtoken=false);
    } else {
    // Log and show 404
    writeLog(file=”missingTemplates”, text=”Missing: #targetPage# | referer=#cgi.http_referer#”);
    include “/errors/404.cfm”;
    }
    }

Use 301 for permanent changes, 302/307 for temporary routing.

See also  How to Migrate ColdFusion Custom Tags to CFCs

8) Fix relative links with a base URL or by moving to absolute paths

  • If your app relocated under a new context root or subfolder, relative links can break.

  • Option A: Set a tag in the HTML head:

    Pros: quick, global fix. Cons: affects all relative references; test thoroughly.

  • Option B: Refactor to absolute URLs using a helper:


    function urlFor(path){ return “https://www.example.com/#reReplace(path, “^/”, “”)#”; }

    Login

9) Update CFML templates that generate links

  • Search for hard-coded “.cfm” or old directory names:

    • Replace “.cfm” with extensionless helpers where policy changed.
    • Normalize trailing slashes.

  • Ensure URL encoding to avoid double-encoding or special-character breaks:

    Search

10) Recreate virtual directories and static asset paths

  • Reconfigure IIS virtual directories or Apache aliases that served /assets, /images, /docs.

  • Confirm CDN rewrite or proxy rules for static content.

  • Consider cache-busting fingerprints so old URLs invalidate properly:

11) Regenerate sitemaps and update robots.txt

  • Build new sitemap.xml reflecting canonical, indexable URLs.
  • Update robots.txt to allow the new paths and disallow old duplicates.
  • Submit the sitemap to Google Search Console/Bing Webmaster Tools.

12) Test 404s, redirects, and core flows; monitor logs

  • Automated tests:

    • Run link checkers in CI against staging and production.

  • Monitor logs:

    • IIS/Apache access logs for 404 and 301/302 counts.
    • ColdFusion logs for onMissingTemplate and application errors.

  • Create a custom 404 page that logs the referer and requested URI:



    Page not found

Risks, common issues, and how to avoid them

  • Mixed HTTP/HTTPS links
    • Symptom: browser warnings, blocked resources.
    • Fix: force HTTPS redirect; update absolute links to https; set HSTS only after confirming no mixed content.
  • Rewrite loops
    • Symptom: ERR_TOO_MANY_REDIRECTS.
    • Fix: order rules from canonical redirects (HTTP→HTTPS, domain) before application rewrites; add conditions to avoid applying the same rule twice.
  • Dropped query strings
    • Symptom: pages missing parameters after redirect.
    • Fix: ensure appendQueryString=”true” (IIS) or QSA flag (Apache).
  • Case sensitivity on Linux
    • Symptom: links work on Windows stage but 404 on Linux prod.
    • Fix: standardize file and URL casing; enforce lowercasing with rewrite rules (optional).
  • Missing ColdFusion mappings
    • Symptom: includes or dynamic URL builders resolve to wrong paths.
    • Fix: replicate this.mappings; prefer per-application definitions.
  • Incorrect connector handlers
    • Symptom: .cfm downloads instead of executing, or 404s for .cfc REST endpoints.
    • Fix: reinstall connector; verify handler mappings for .cfm/.cfc; enable REST mapping if used.
  • UTF-8 and encoding issues
    • Symptom: URLs with accents or special characters break or double-encode.
    • Fix: set consistent charset in ColdFusion (this.charset=”utf-8″); use encodeForURL; configure URI decoding in web server to UTF-8.
  • Trailing slash inconsistency
    • Symptom: duplicate content or busted relative paths.
    • Fix: choose a canonical policy; redirect the other; ensure relative assets account for the policy.
  • Session identifiers in URLs (jsessionid)
    • Symptom: duplicate URLs and cache poisoning.
    • Fix: disable URL rewriting of sessions if possible; rely on cookies; add rules to strip jsessionid from canonical links.

Quick reference table:

Issue Symptom Avoidance/Fix
Dropped query string Lost filters or detail pages Use QSA (Apache) or appendQueryString (IIS)
Rewrite loop Too many redirects Order rules; add conditions to detect already-canonical URLs
Missing .cfc handler API 404s Map .cfc to connector; allow REST endpoints
Case mismatch Random 404s on Linux Enforce casing; rename files or rewrite to lowercase
Extension policy change Legacy .cfm links 404 301 redirect .cfm to extensionless or vice versa

Post-migration Checklist / validation steps

  • Web server and connector

    • .cfm and .cfc requests execute via the connector.
    • Health check endpoint responds 200.
    • No unexpected file downloads of CFML files.

  • Redirects and canonicalization

    • HTTP→HTTPS 301 in a single hop.
    • www vs non-www enforced consistently.
    • Legacy .cfm or old directories 301 to new URLs.
    • No redirect chains (>1 hop) on top pages.

  • URL structure

    • Extension policy implemented (extensionless or explicit .cfm).
    • Trailing slash policy consistent.
    • Query strings preserved during rewrites.

  • Content and assets

    • Static assets (CSS/JS/images) load over HTTPS without mixed content.
    • Virtual directories and aliases resolved.
    • CDN paths valid, with cache-busting fingerprints if used.

  • Application behavior

    • Forms, login, and key workflows work from entry via redirected links.
    • encodeForURL used on dynamic links.
    • Application.cfc mappings present and correct.

  • SEO and observability

    • Regenerated sitemap submitted to search engines.
    • robots.txt updated and reachable.
    • 404 volume monitored; spikes investigated.
    • Custom 404 logs record referer and URI.

  • External dependencies

    • Update paid ads, emails, and social links.
    • Update integrations and partners with new endpoints.

  • Automated scans

    • Run a crawler against production and fix high-priority 404s:

      npx linkinator https://www.example.com/ –recurse –skip “.*.(pdf|jpg|png)$”

  • Security and Performance

    • HSTS enabled after resolving mixed content.
    • Compression and caching headers applied to static assets.
See also  How to Migrate ColdFusion to Azure App Service

Practical configuration snippets

ColdFusion Application.cfc: environment-aware base URL

component {
this.name=”MyApp”;
this.mappings={“/views”=expandPath(“/app/views”)};

variables.baseUrl = cgi.https EQ “on” ? “https://www.example.com” : “http://www.example.com“;

boolean function onRequestStart(string targetPage){
request.baseUrl = variables.baseUrl;
return true;
}
}

Usage in a template:

Login

IIS: enforce HTTPS and canonical host














Apache: strip jsessionid and enforce HTTPS

RewriteEngine On

Enforce HTTPS

RewriteCond %{HTTPS} !=on
RewriteRule ^ https://%{HTTP_HOST}%{REQUEST_URI} [R=301,L]

Strip jsessionid

RewriteCond %{THE_REQUEST} \s/+(.+);jsessionid=[^\s]+
RewriteRule ^ %1 [R=301,L]

Example workflow to fix broken links fast

  1. Crawl production and export every 404 and top landing page.
  2. Prioritize fixes:
    • Add explicit 301 redirect rules for top Legacy URLs.
    • Restore missing mappings and handler settings.
    • Port and test rewrite rules in staging, then deploy to production.
  3. Re-crawl; confirm 301s happen in one hop and 404 volume drops.
  4. Regenerate sitemap and submit to search engines.
  5. Monitor logs and analytics for at least two weeks, capturing new broken link sources.

FAQ

Should I keep .cfm extensions visible or move to extensionless URLs?

Both are valid. Extensionless URLs are cleaner and more future-proof, but require:

  • Rewrite rules to map clean paths to .cfm internally.
  • 301 redirects from legacy .cfm URLs to preserve SEO.
    If you have a vast archive of .cfm links and limited resources, you can keep .cfm visible but still standardize casing, trailing slashes, and canonical host. Whichever you choose, enforce it consistently.

When should I use 301 vs 302/307 redirects during migration?

  • Use 301 (permanent) when a URL has definitively changed.
  • Use 302/307 (temporary) when you’re testing, doing canary releases, or planning to revert.
    Search engines treat 301 as a signal to transfer link equity; aim to finalize to 301s quickly once confident.

Why did my links break after moving from Windows to Linux?

Linux filesystems are case-sensitive; Windows typically isn’t. If your templates link to /Images/Logo.png but the file is images/logo.png, Linux will 404. Standardize casing across file names and URLs, and consider rewrite rules to normalize casing or redirect to the canonical lowercase path.

How do I find every broken link across a large ColdFusion site?

Combine approaches:

  • Crawl with tools like Linkinator, Screaming Frog, or wget.
  • Analyze Server logs for 404s and referring pages.
  • Add a custom 404 that logs the requested URI and referer.
  • Use analytics (Top 404 report) to prioritize fixes.
    Automate these checks in CI/CD against a staging environment before production deployments.

About the author

Aaron Longnion

Aaron Longnion

Hey there! I'm Aaron Longnion — an Internet technologist, web software engineer, and ColdFusion expert with more than 24 years of experience. Over the years, I've had the privilege of working with some of the most exciting and fast-growing companies out there, including lynda.com, HomeAway, landsofamerica.com (CoStar Group), and Adobe.com.

I'm a full-stack developer at heart, but what really drives me is designing and building internet architectures that are highly scalable, cost-effective, and fault-tolerant — solutions built to handle rapid growth and stay ahead of the curve.

View all posts

You may also like