Overview of the Problem

A 404 Not Found error from a ColdFusion REST API indicates that the requested endpoint or resource cannot be located. Practically, this can mean one of two things:

• The web server (IIS/Apache) does not route the request to ColdFusion at all.
• ColdFusion receives the request but cannot match it to a deployed REST service, component, or method.

In ColdFusion, REST routing involves several layers: web server routing to ColdFusion, ColdFusion REST service registration, CFC and method annotations, and application-level Configuration. A break at any layer can produce a 404.

Key idea: The URL must match this general pattern:

• http(s)://host[:port]/rest/{service-mapping}/{component-restPath}/{method-restPath}/…

If any part of that chain is missing or misconfigured, you get a 404.

---

Possible Causes

Quick reference (Cause / Solution):

• Wrong URL path or base mapping / Use the correct /rest/{mapping}/… path; verify mapping name and service root.
• REST service not registered or not deployed / Register in ColdFusion Administrator (REST services) or reinitialize programmatically; refresh/redeploy after changes.
• CFC or method missing annotations / Add rest=”true” on component; httpMethod, restPath, produces/consumes on methods.
• HTTP method mismatch / Ensure method annotations include the correct httpMethod (GET/POST/etc.) or call the endpoint with the correct HTTP verb.
• Rewrite rules intercepting /rest / Update IIS/Apache rewrite rules to exclude /rest from SES/URL rewriting to index.cfm or other handlers.
• Connector or servlet mapping issues / Ensure IIS/Apache connector forwards /rest/* to ColdFusion; verify site bindings and handler mappings.
• Incorrect Application.cfc Configuration / Confirm mappings, onRequest handlers, and optional rest initialization don’t block /rest.
• Case sensitivity and trailing slashes / Match restPath exactly; remove/add trailing slashes as needed; ensure path parameter names match.
• Stale Deployment or cache / Refresh REST services, clear template cache, restart the app or ColdFusion service when necessary.
• Permissions/Security filters / Web.config or server rules might block the path; verify authorization and IP restrictions.

---

Step-by-Step Troubleshooting Guide

Step 1: Identify where the 404 originates (web server vs. ColdFusion)

• Use curl or a browser developer tool to inspect headers.
  • If the response Server header is IIS/Apache and there’s no ColdFusion header, the request likely never reached ColdFusion.
  • If a ColdFusion-specific 404 template or JSON body appears, ColdFusion likely produced the 404.
• Check logs:
  • IIS: %SystemDrive%\inetpub\logs\LogFiles… (look for sc-status=404 and substatus codes like 2, 3, 5).
  • Apache: error_log and access_log.
  • ColdFusion: cfusion/logs/ (application.log, coldfusion-error.log, exception.log, server.log). Look for REST-related messages around the request time.
• Test the ColdFusion connector by hitting a known CF page (e.g., /index.cfm) on the same site. If that renders but /rest/404s, the problem is REST-specific. If it doesn’t render, fix connector or site bindings first.

Step 2: Verify the REST URL structure and base mapping

• The URL must be of the form: /rest/{service-mapping}/{component-restPath}/{method-restPath}
• Confirm the mapping name:
  • ColdFusion Administrator > REST Services: note the “REST Path” or “Service Mapping” you configured.
• Try a minimal endpoint call:
  • If your mapping is api and your component restPath is users, a GET to /rest/api/users might be valid if the method restPath is empty or index-like, otherwise you need /rest/api/users/{id}.

Step 3: Confirm the REST service is registered and deployed

• In ColdFusion Administrator:
  • Go to “REST Services.”
  • Make sure your service directory is registered and Deployed. If you see it but not deployed or out of date, click Refresh/Deploy.
  • If you added/renamed CFCs or methods, click Refresh on the service to redeploy metadata.
• If you prefer code-based Deployment, ensure your initialization code runs on app start and refreshes the REST application after changes.

Step 4: Validate CFC and method annotations

Your component must be REST-enabled and methods must declare HTTP method and path.

Example CFC:

component
rest=”true”
restPath=”users”
output=”false”
{
/**

• GET /rest/api/users/{id}
  */
  remote struct function getUser(required string id)
  httpMethod=”GET”
  restPath=”{id}”
  produces=”application/json”
  {
  return { id = id, name = “Example User” };
  }

/**
 * POST /rest/api/users
 */
remote struct function createUser(required struct body)
    httpMethod="POST"
    restPath=""
    consumes="application/json"
    produces="application/json"
{
    // body is typically read via getHttpRequestData().content and deserializeJSON
    var data = deserializeJSON( toString( getHttpRequestData().content ) );
    return { created = true, data = data };
}

}

Checklist:

• The component has rest=”true”.
• The component’s restPath is set (e.g., users).
• Each REST method has httpMethod and restPath (even if restPath is empty).
• Method access is often remote for REST exposure.
• Parameter names in restPath placeholders match function argument names.

Step 5: Match HTTP verb and method annotations

• If you call POST but the method is annotated with httpMethod=”GET”, ColdFusion will not match the route, leading to 404.
• Likewise for PUT, DELETE, PATCH; ensure your endpoint and client agree on the verb.

Step 6: Check Application.cfc and mappings

• Ensure Application.cfc doesn’t block /rest with onRequest or SES-routing logic.
• If you do URL rewriting to index.cfm, exclude /rest paths (see Step 7).
• If using mappings (this.mappings) to reach your API directory at runtime, confirm they resolve correctly. Misresolved paths can prevent ColdFusion from finding CFCs.
• If you programmatically initialize the REST app, verify it runs on application start and points to the correct directory.

Minimal Application.cfc skeleton:

component {
this.name = “MyApp”;
this.sessionManagement = true;

function onApplicationStart() {
    // If you initialize REST programmatically, do it here.
    // Example (if applicable to your setup):
    // restInitApplication("MyAppREST", expandPath("/api"));
    return true;
}

function onRequestStart(string targetPage) {
    // Ensure custom routing does NOT swallow /rest requests
    // if ( listFirst(cgi.PATH_INFO, "/") NEQ "rest" ) { ... }
}

}

Note: If you use programmatic initialization, confirm the function signatures and arguments for your ColdFusion version. When in doubt, use CF Administrator to register/refresh the service.

Step 7: Inspect rewrite rules and virtual directories

• IIS URL Rewrite (web.config) often routes requests to /index.cfm; exclude /rest to avoid interception.

IIS rule example to ignore /rest:

Place this rule above other SES rules.

• Apache mod_rewrite example to ignore /rest:

RewriteEngine On
RewriteRule ^rest/ – [L]
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule ^(.*)$ /index.cfm/%{REQUEST_URI} [QSA,PT,L]

• Also ensure no virtual directory or static folder named rest conflicts with the servlet mapping.

Step 8: Reload/clear caches and redeploy

• In ColdFusion Administrator > REST Services, click Refresh on your service.
• Clear template cache (Caching > Clear Template Cache) if templates or mappings changed.
• If you use application-level flags (e.g., reinit), trigger a reinit to rebuild routes.
• As a last resort, restart the ColdFusion service, especially after adding connectors or changing core mappings.

Step 9: Validate Security and permissions

• Check web.config (IIS) or .htaccess/Server config (Apache) for Authentication/authorization rules blocking /rest.
• Confirm that file permissions allow ColdFusion to read the API CFC directories.
• If using a locked-down ColdFusion or WAF, verify that /rest is allowed.

Step 10: Build a minimal reproducible endpoint

• Create a new folder with one CFC (like the example above), register it as a new REST service mapping (e.g., testapi), and call:
  • GET /rest/testapi/users/123
• If this works, the problem is in your original app’s routes, annotations, or rewrite rules. If it fails, focus on server/connector/admin configuration.

---

Configuration and Code Examples

Registering a REST Service in ColdFusion Administrator

1. Open ColdFusion Administrator.
2. Navigate to Services > REST Services.
3. Click Add.
4. Select the directory containing your REST CFCs.
5. Provide a unique REST Path (e.g., api). This becomes the base mapping.
6. Deploy the service. If you change CFCs later, click Refresh to redeploy.

Minimal Application.cfc with cautious routing

component {
this.name = “MyApp”;
this.sessionManagement = true;

function onRequestStart(targetPage) {
    // If you have custom routing, explicitly bypass /rest
    var firstSegment = listFirst(cgi.PATH_INFO, "/");
    if ( compareNoCase(firstSegment, "rest") == 0 ) {
        return true;
    }
    // ... your other routing logic
    return true;
}

}

Sample REST CFC

component rest=”true” restPath=”ping” output=”false” {
/**

• GET /rest/api/ping
  */
  remote struct function check()
  httpMethod=”GET”
  restPath=””
  produces=”application/json”
  {
  return { ok = true, ts = now() };
  }
  }

Testing with curl

GET

curl -i http://localhost/rest/api/ping

POST example

curl -i -X POST http://localhost/rest/api/users \
-H “Content-Type: application/json” \
-d ‘{“name”:”Ada Lovelace”}’

Expected 200 OK responses; a 404 indicates routing/registration issues per the steps above.

---

Common mistakes and How to Avoid Them

• Forgetting to deploy or refresh the REST service after code changes.
• Using the wrong base mapping in the URL (e.g., /api instead of /rest/api).
• Missing rest=”true” on the CFC or missing httpMethod/restPath on methods.
• SES/URL rewrite rules capturing /rest unintentionally.
• Calling a POST endpoint with GET (or vice versa), leading to route mismatch.
• Renaming directories without updating ColdFusion mappings or Administrator entries.
• Assuming changes take effect immediately without redeploy/reinit or Cache clearing.
• Case mismatches in restPath or parameters (especially on case-sensitive environments).

Avoid these by maintaining a deployment Checklist and small validation tests for each API change.

---

Prevention Tips / Best practices

• Document and standardize your REST URL scheme and mappings.
• Keep REST CFCs in a dedicated directory; register that directory once and refresh on changes.
• Automate REST service refresh as part of deployment, or use an application-level reinit endpoint secured to admins.
• Exclude /rest from all SES or MVC rewrites in IIS/Apache.
• Version your APIs (e.g., /rest/api/v1/…) so new routes don’t break old ones.
• Write lightweight endpoint smoke tests (curl/Postman/Newman) to run after each deployment.
• Log REST requests and responses (at least status and path) during development; reduce verbosity in production.
• Validate config drift regularly: confirm connector, handler mappings, and site bindings in IIS/Apache.
• Keep ColdFusion updated to the latest stable update for your version (2018/2021/2023) to leverage REST fixes and improvements.

---

Key Takeaways

• A ColdFusion REST 404 can originate from either the web server or ColdFusion itself; determine which first.
• Confirm the full path: /rest/{mapping}/{component-restPath}/{method-restPath}; validate HTTP verb and parameters.
• Ensure REST services are registered and deployed, and refresh them after code changes.
• Protect the /rest path from rewrite rules and custom routing.
• Use minimal reproducible endpoints and automated tests to quickly isolate problems.

---

FAQ

Why do I get a 404 only on POST/PUT but GET works?

This usually points to an HTTP method mismatch. Ensure the method has httpMethod=”POST” (or PUT) and that your client uses that verb. Also verify consumes/produces headers; if your method expects JSON and you send form data, ColdFusion may not match the route, producing a 404.

How can I tell if IIS/Apache or ColdFusion generated the 404?

Check response headers and logs. If the web Server logs a 404 and ColdFusion logs are quiet at that time, the request didn’t reach ColdFusion. A ColdFusion 404 typically leaves traces in application.log/server.log and often shows a ColdFusion-styled error page unless you return a custom JSON 404.

Do I need to restart ColdFusion to pick up new REST endpoints?

Not typically. Use ColdFusion Administrator > REST Services > Refresh on the specific service, or trigger an application reinit if you deploy programmatically. Restarting ColdFusion is a last resort for connector or core config changes.

Can URL rewriting for my site break REST endpoints?

Yes. If you funnel all requests to index.cfm, you must explicitly exclude /rest paths. Add early rewrite rules in IIS/Apache to bypass /rest so ColdFusion’s REST servlet can handle them directly.