lc-analyze-error

name	lc:analyze-error
description	Paste a Laravel stacktrace and get root cause analysis with suggested fix.
argument-hint	[analyze | fix | fix --dry-run]
user-invocable	true
allowed-tools	Read Grep Bash Edit Write Glob

Analyze Laravel Error

Parse a Laravel stacktrace or error message, identify the root cause, read the relevant source files, and provide a specific fix.

Subcommands

Subcommand	Description
(no argument)	Paste an error after invoking. Analyzes and reports root cause with suggested fix.
fix	Analyze the error and apply the suggested fix, with confirmation before each change.
fix --dry-run	Analyze the error and show exactly what changes would be made without applying them.

In all modes, the user pastes the error output after invoking the skill.

Process

Step 1: Receive and Parse the Error

The user will paste an error after invoking this skill. Parse the error output to extract:

1. Exception class: e.g., Illuminate\Database\QueryException, ErrorException, BadMethodCallException
2. Error message: The human-readable description of what went wrong
3. File and line: The exact file and line number where the error occurred
4. SQL query (if applicable): The raw SQL that failed
5. Stack trace: The chain of method calls leading to the error

If the error is a standard Laravel error page (HTML), extract the relevant information from the HTML structure. If it is a CLI error, parse the text output.

Step 2: Read the Source File

1. Use Read to load the file where the error occurred, focusing on the line number from the stacktrace with surrounding context (approximately 20 lines before and after).
2. Identify the exact code that triggered the error.
3. If the error originated in vendor code, trace back up the stack trace to find the first application file (in app/, routes/, resources/, database/, config/) -- that is where the fix needs to happen.

Step 3: Read Related Files

Based on the error type, read additional files for context:

For Database/Query Errors:

• The model file involved (from the stack trace or query)
• The migration that defines the table/columns
• The observer (if the error happens during save/create)

For Relationship Errors:

• The model defining the relationship
• The related model
• The migration for both tables (to check FK definitions)

For View/Blade Errors:

• The Blade view file
• The Livewire component or controller that renders it
• The data passed to the view

For Route Errors:

• The routes file
• The controller or Livewire component for the route
• Middleware definitions

For Authentication/Authorization Errors:

• The auth configuration (config/auth.php)
• The relevant guard and provider setup
• The policy file if applicable

Step 4: Identify Root Cause

Classify the error into one of these common patterns and provide specific diagnosis:

Database Errors

Pattern	Exception	Root Cause
SQLSTATE[42S02]	QueryException	Table doesn't exist -- migration not run or wrong table name
SQLSTATE[42S22]	QueryException	Column doesn't exist -- typo, migration not run, or column removed
SQLSTATE[23000]	QueryException	Integrity constraint violation -- duplicate entry, null in NOT NULL, FK violation
SQLSTATE[42000]	QueryException	Syntax error in SQL -- usually from raw queries or incorrect query builder usage
SQLSTATE[HY000]: 1215	QueryException	Cannot add FK constraint -- type mismatch or referenced table missing
SQLSTATE[22001]	QueryException	Data too long -- string exceeds column length

Eloquent/Model Errors

Pattern	Exception	Root Cause
Call to undefined relationship	BadMethodCallException	Relationship method doesn't exist on model
Property does not exist	ErrorException	Accessing undefined property (possible missing relationship or accessor)
Mass assignment	MassAssignmentException	Column not in $fillable or $guarded is blocking it
Model not found	ModelNotFoundException	findOrFail() or firstOrFail() with non-existent ID
Call to a member function on null	ErrorException	Accessing method on null relationship result

View/Blade Errors

Pattern	Exception	Root Cause
Undefined variable	ErrorException	Variable not passed from controller/component to view
Property not found on component	Livewire error	Wire:model bound to non-existent property
Component not found	ComponentNotFoundException	Livewire component class missing or not registered
View not found	InvalidArgumentException	Blade file doesn't exist at expected path

Authentication/Authorization

Pattern	Exception	Root Cause
Unauthenticated	AuthenticationException	User not logged in, session expired, or wrong guard
This action is unauthorized	AuthorizationException	Policy check failed
Route [login] not defined	RouteNotFoundException	Missing named route for auth redirect

Type/Logic Errors

Pattern	Exception	Root Cause
Typed property must not be accessed before initialization	Error	Livewire property declared with type but no default value
Cannot access offset of type null	TypeError	Trying to array-access a null value
Argument #N must be of type X, Y given	TypeError	Wrong argument type passed to method
Enum case not found	ValueError	Invalid value for PHP enum cast

Step 5: Provide the Fix

For each error, provide:

1. Root cause explanation (1-2 sentences explaining WHY this happened, not just WHAT happened)
2. The specific file and line that needs to change
3. The exact code fix showing before and after:

   // BEFORE (line 45 in app/Models/Property.php):
   return $this->office->name;
   
   // AFTER:
   return $this->office?->name;
   

4. Prevention advice (how to avoid this in the future)

Step 6: Check for Related Issues

After identifying the primary fix, check if the same pattern exists elsewhere:

1. Use Grep to search for similar problematic patterns in other files.
2. If found, report them as "Related issues that may need the same fix" with file paths and line numbers.

Step 7: Apply Fix (fix mode)

In fix mode:

1. Show the proposed fix with before/after diff.
2. Ask for confirmation before applying.
3. Use Edit to apply the change.
4. If related issues were found, ask if the user wants to fix those too.

In fix --dry-run mode:

1. Show the proposed fix with before/after diff.
2. Show all related issues and their proposed fixes.
3. Do not apply any changes.

In default mode (no subcommand):

1. Show the analysis, root cause, and suggested fix.
2. Ask the user if they want to apply the fix.

Error Parsing Tips

Laravel CLI Errors

   Illuminate\Database\QueryException

  SQLSTATE[42S22]: Column not found: 1054 Unknown column 'properties.group_id' in 'where clause'
  (Connection: mysql, SQL: select * from `properties` where `properties`.`group_id` = 1)

  at vendor/laravel/framework/src/Illuminate/Database/Connection.php:829
  ...
  at app/Http/Controllers/PropertyController.php:25

Extract: Exception class, SQL state, column name, table, and the app file from the trace.

Laravel Log Errors

[2026-04-06 10:15:23] production.ERROR: Call to a member function format() on null
{"exception":"[object] (Error(code: 0): ... at /var/www/html/app/Models/Schedule.php:45)"}

Extract from JSON structure within the log line.

Livewire Errors

Livewire\Exceptions\PropertyNotFoundException
Property [$selectedUser] not found on component: [calendar]

These reference the Livewire component name, which maps to a Blade file in resources/views/livewire/.

Vite/Asset Errors

If the error is related to Vite, assets, or frontend compilation, check:

• vite.config.js configuration
• package.json dependencies
• Whether npm run dev is running

Known Project-Specific Issues

Based on the project's CLAUDE.md, watch for these specific patterns:

1. Schema dump conflicts: If migrate:fresh errors mention missing tables, check for database/schema/mysql-schema.sql.
2. Foreign key order: The project has known FK dependency issues (files -> clients -> properties).
3. Organization rename: Old code may still reference group_id instead of organization_id, Group instead of Organization.
4. Custom notifications: Code using DatabaseNotification should use App\Models\Notification instead.
5. Translation errors: Using __() instead of text() will not work with Laratext.

Output Format

ERROR ANALYSIS
===============

Exception: Illuminate\Database\QueryException
Message: SQLSTATE[42S22]: Column not found: 1054 Unknown column 'properties.group_id'

ROOT CAUSE
===========
The 'properties' table was renamed from 'group_id' to 'organization_id' in the
Organization rename migration (2025_12_25_023229), but this query still uses the
old column name.

LOCATION
=========
File: app/Http/Controllers/PropertyController.php
Line: 25
Code: Property::where('group_id', $organizationId)->get();

FIX
====
Change 'group_id' to 'organization_id':

  // Line 25
  - Property::where('group_id', $organizationId)->get();
  + Property::where('organization_id', $organizationId)->get();

RELATED ISSUES
===============
Found 3 other files with the same pattern:
  - app/Services/PropertyService.php:42
  - app/Jobs/SyncPropertyJob.php:18
  - resources/views/livewire/properties/index.blade.php:33

Apply fix? [Waiting for confirmation]