laravel-debugging-prompts

name	laravel:debugging-prompts
description	Create effective debugging prompts—include error messages, stack traces, expected vs actual behavior, logs, and attempted solutions

Debugging Prompts

Debugging with AI requires complete information. Missing context means generic suggestions that don't solve your specific problem.

Error Messages and Stack Traces

Incomplete

"Getting an error in the payment controller"

Complete

"Getting error when processing payment:

Error:

Illuminate\Database\QueryException: SQLSTATE[23000]: 
Integrity constraint violation: 1452 Cannot add or update a child row: 
a foreign key constraint fails (`app`.`payments`, CONSTRAINT `payments_order_id_foreign` 
FOREIGN KEY (`order_id`) REFERENCES `orders` (`id`) ON DELETE CASCADE)

Stack trace:

#0 app/Services/PaymentService.php(45): Payment::create()
#1 app/Http/Controllers/PaymentController.php(28): PaymentService->process()
#2 vendor/laravel/framework/src/Illuminate/Routing/Controller.php(54)

Context:

• Laravel 13.x, MySQL 8.0
• Happens when order_id doesn't exist in orders table
• Payment data: ['order_id' => 999, 'amount' => 5000, 'status' => 'pending']
• Order 999 doesn't exist in database"

Why it works: Complete error, stack trace, context, and the specific data causing the issue.

Expected vs Actual Behavior

Vague

"The API isn't returning the right data"

Specific

"Product API returning incorrect data:

Expected behavior:

{
  "data": {
    "id": 1,
    "name": "Widget",
    "price": "29.99",
    "category": {
      "id": 5,
      "name": "Tools"
    }
  }
}

Actual behavior:

{
  "data": {
    "id": 1,
    "name": "Widget",
    "price": 2999,
    "category": null
  }
}

Issues:

1. Price is in cents (2999) instead of formatted dollars ("29.99")
2. Category is null even though product has category_id = 5

Code:

// ProductController@show
return new ProductResource($product);

Product has category_id = 5 in database, but relationship not loading."

Why it works: Shows exact expected vs actual output, identifies specific issues, includes relevant code.

Log Entries and State

Insufficient

"Something's wrong with the queue"

Sufficient

"Job failing in queue:

Log entries:

[2024-01-15 10:30:15] local.ERROR: Job failed: ProcessOrderJob
{"order_id":123,"exception":"Stripe\\Exception\\InvalidRequestException: 
No such customer: cus_invalid","attempts":3}

[2024-01-15 10:30:15] local.INFO: Order state before job
{"id":123,"status":"pending","stripe_customer_id":"cus_invalid"}

Job code:

public function handle()
{
    $customer = $this->stripe->customers->retrieve(
        $this->order->stripe_customer_id
    );
    // ...
}

State:

• Order 123 has stripe_customer_id = "cus_invalid"
• Customer doesn't exist in Stripe
• Job has retried 3 times, now in failed_jobs table
• Using Laravel 13.x with Horizon"

Why it works: Includes logs, state information, relevant code, and context about retries.

Hypotheses and Evidence

Weak

"I think it's a caching issue"

Strong

"Suspect Redis cache is stale:

Hypothesis: Product prices are cached but not invalidating on update.

Evidence:

1. Updated product price in database: UPDATE products SET price = 3999 WHERE id = 1
2. Database shows: SELECT price FROM products WHERE id = 1 → 3999
3. API returns old price: GET /api/products/1 → "price": "29.99"
4. After php artisan cache:clear, API returns correct price: "price": "39.99"

Caching code:

public function show(Product $product)
{
    $cached = Cache::remember("product.{$product->id}", 3600, function () use ($product) {
        return new ProductResource($product);
    });
    return $cached;
}

Problem: Cache key doesn't invalidate when product updates. Need cache invalidation in ProductObserver or remove caching from show method."

Why it works: Clear hypothesis, concrete evidence, relevant code, proposed solution.

Attempted Solutions

Unhelpful

"I tried some things but nothing worked"

Helpful

"Attempted solutions and results:

Attempt 1: Added eager loading

$products = Product::with('category')->get();

Result: Still getting N+1 queries. Debugbar shows 101 queries (1 for products, 100 for categories).

Attempt 2: Used load() after fetching

$products = Product::all();
$products->load('category');

Result: Same issue, still 101 queries.

Attempt 3: Checked relationship definition

// In Product model
public function category()
{
    return $this->belongsTo(Category::class);
}

Result: Relationship looks correct. Foreign key category_id exists in products table.

Current state: Eager loading syntax seems correct but not working. Using Laravel 13.x. What am I missing?"

Why it works: Shows what was tried, exact code used, results observed, helps avoid suggesting already-tried solutions.

Debugging Templates

Template: Error Report

**Error:** [Full error message]
**Stack trace:** [Complete stack trace]
**File/Line:** [Where error occurs]
**Context:** [Laravel version, packages, environment]
**Data:** [Input data causing error]
**Expected:** [What should happen]

Template: Unexpected Behavior

**Expected:** [Describe expected behavior with example]
**Actual:** [Describe actual behavior with example]
**Code:** [Relevant code snippet]
**State:** [Database state, variable values]
**Environment:** [Laravel version, Sail/host, packages]

Template: Performance Issue

**Problem:** [Describe slow operation]
**Metrics:** [Response time, query count, memory usage]
**Query log:** [Slow queries from Debugbar/Telescope]
**Code:** [Code causing performance issue]
**Dataset size:** [Number of records involved]
**Attempted:** [Optimizations already tried]

Quick Reference

Debug effectively with AI:

• Complete errors - Full message, stack trace, file/line
• Show both sides - Expected vs actual behavior
• Include logs - Error logs, info logs, state dumps
• Share evidence - Database queries, API responses, variable dumps
• Document attempts - What you tried, exact code, results
• Provide context - Laravel version, environment, packages

More information = faster solutions. When debugging, over-communicate.