---

name: Wheels Debugging description: Troubleshoot common Wheels errors and provide debugging guidance. Use when encountering errors, exceptions, or unexpected behavior. Provides error analysis, common solutions, and debugging strategies for Wheels applications.

Wheels Debugging

Common Errors

"No matching function [RENDERPAGE] found"

Cause: Using wrong function name - CFWheels uses renderView() not renderPage()

Solution: Change to correct function name

Copy❌ renderPage(action="new")
✅ renderView(action="new")

"Missing argument name" Error

Cause: Mixed positional and named arguments

Solution: Use consistent argument style

Copy❌ hasMany("comments", dependent="delete")
✅ hasMany(name="comments", dependent="delete")

❌ .resources("sessions", only="new,create")
✅ .resources(name="sessions", only="new,create")

"key [onCreate,onUpdate] doesn't exist"

Cause: Using comma-separated values in validation when parameter

Solution: Remove the when parameter - validations run on both create and update by default

Copy❌ validatesConfirmationOf(properties="password", when="onCreate,onUpdate")
✅ validatesConfirmationOf(properties="password")

"Can't cast Object type [Query] to [Array]"

Cause: Using Array functions on queries

Solution: Use query methods

Copy❌ ArrayLen(post.comments())
✅ post.comments().recordCount

"Association not found" Error

Cause: Association not properly defined or typo

Solution:

1. Check model config() for association definition
2. Verify association name matches
3. Check model name spelling

"Table not found" Error

Cause: Migration not run or table name mismatch

Solution:

Copywheels dbmigrate latest

"Column not found" Error

Cause: Property doesn't exist in database

Solution:

1. Add column via migration
2. Check property name spelling
3. Verify case sensitivity

Debugging Tools

Enable Debug Output

Copy// In config/settings.cfm
set(showDebugInformation=true);
set(showErrorInformation=true);

Inspect Variables

Copy<cfdump var="#post#" label="Post Object">
<cfabort>

Check SQL Queries

Copy// Wheels logs all SQL to debugging output
// Look for red SQL queries (errors)

Browser Testing for Debugging

When debugging UI/view issues, use browser MCP tools to verify:

Check Page Rendering

Copy// Use available MCP tool (in order of preference):

// Option 1: Puppeteer MCP (preferred)
mcp__puppeteer__puppeteer_navigate(url="http://localhost:PORT/controller/action")
mcp__puppeteer__puppeteer_screenshot(name="debug-screenshot")

// Option 2: Playwright MCP
mcp__playwright__playwright_navigate(url="http://localhost:PORT/controller/action")
mcp__playwright__playwright_screenshot()

// Option 3: Browser MCP (fallback)
mcp__browsermcp__browser_navigate(url="http://localhost:PORT/controller/action")
mcp__browsermcp__browser_screenshot()

Verify Form Submissions

Copy// Navigate to form
mcp__puppeteer__puppeteer_navigate(url="http://localhost:PORT/posts/new")

// Fill and submit
mcp__puppeteer__puppeteer_click(selector="input[name='post[title]']")
// Check for errors in response

Check for JavaScript Errors

Use browser console output to identify client-side issues that might affect form submissions or dynamic content.

---

Generated by: Wheels Debugging Skill v1.1