---
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
```cfm
❌ renderPage(action="new")
✅ renderView(action="new")
```

### "Missing argument name" Error

**Cause:** Mixed positional and named arguments

**Solution:** Use consistent argument style
```cfm
❌ 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
```cfm
❌ 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
```cfm
❌ 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:**
```bash
wheels 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
```cfm
// In config/settings.cfm
set(showDebugInformation=true);
set(showErrorInformation=true);
```

### Inspect Variables
```cfm
<cfdump var="#post#" label="Post Object">
<cfabort>
```

### Check SQL Queries
```cfm
// 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
```javascript
// 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
```javascript
// 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