Debugging Cookbook

This page covers the most common problems developers encounter while working on Exowpee, with practical solutions for each.

I got a 403 Forbidden

The system is telling you “I know who you are, but you are not allowed to do this.”

Check 1: Does the user’s profile have the required permission?

# Get the current user's permissions
GET /v1/auth/me
Authorization: Bearer <token>

Look at the permissions array in the response. Is the required permission listed? For example, if you are trying to create a product, you need products.create.

Check 2: Is the policy checking the right thing?

Find the relevant Policy class (e.g., ProductPolicy) and check what permission it requires:

// In ProductPolicy
public function create($user): bool
{
    return (bool) auth()->profile()?->hasPermissionTo('products.create');
}

Make sure the permission name matches exactly — products.create is not the same as create_product.

Check 3: Is the company context correct?

Permissions are scoped per company. If the user switched profiles and the new profile does not have the required role, they will get a 403.

Check 4: Is this an agent trying to access a user-only endpoint?

IAM management endpoints (/v1/iam/*) require auth:api only. If an agent tries to access them, they get a 403.

I got a 422 Validation Error

The request data failed validation. The response body tells you exactly what is wrong.

Check 1: Read the error response

{
  "message": "The given data was invalid.",
  "errors": {
    "items.0.allocations.0.quantity": ["The quantity must be greater than 0."],
    "total": ["The total field is required."]
  }
}

Each key in the errors object is the field that failed, and the value is an array of error messages.

Check 2: Find the FormRequest class

The validation rules are defined in the corresponding FormRequest. For POST /v1/order/orders, look at CreateOrderRequest:

public function rules()
{
    return [
        'total' => 'required|numeric|min:0',
        'items' => 'required|array|min:1',
        'items.*.quantity' => 'required|integer|min:1',
        // ...
    ];
}

Check 3: Check for authorization failures in FormRequest

If authorize() returns false, you get a 403, not a 422. But if the error message is vague, the authorize method might be the issue.

Data is not showing up

You created a record but it does not appear in queries.

Check 1: Are you in the right company context?

The most common cause. Data is scoped to the active company from the JWT token. If you created data in Company A but are now querying in Company B, you will not see it.

# Verify your current context
GET /v1/auth/me
# Check the company_id in the response

Check 2: Is the data organization-scoped or company-scoped?

Products are organization-scoped (shared across all companies). Orders are company-scoped (only visible in the company where they were created). If you are looking for a product, any company in the organization should see it. If you are looking for an order, you must be in the right company.

Check 3: Was the record soft-deleted?

Many models use soft deletes. The record exists in the database but has a deleted_at timestamp. Standard queries exclude soft-deleted records.

Check 4: Check pagination

The API uses cursor pagination. If you are not seeing all records, check if there is a next_cursor in the response — you may need to fetch the next page.

WebSocket events are not working

Clients are not receiving real-time updates.

Check 1: Is Laravel Reverb running?

php artisan reverb:start

Reverb must be running for WebSocket connections to work. Check the console output for errors.

Check 2: Is the queue worker running?

ClientRefresh and ResourceUpdated events run on the client_refresh queue. If the queue worker is not processing jobs, events will be queued but not broadcast.

php artisan queue:work --queue=client_refresh

Check 3: Is the client connecting to the right channel?

Private channels require the company ID:

echo.private(`clientRefresh.${companyId}`)

If companyId is wrong or undefined, the client will connect to the wrong channel.

Check 4: Is channel authorization working?

Private channels require auth. Check routes/channels.php for the authorization logic.

Migration failed

Check 1: Is the database accessible?

php artisan db:monitor
# or test the connection directly
php artisan tinker
>>> DB::connection()->getPdo();

Check 2: Does the migration have a dependency on another migration?

If a migration references a table that does not exist yet, it will fail. Check the migration order (timestamps in filenames).

Check 3: Is there a conflicting migration?

If someone else added a migration that modifies the same table, there may be a conflict. Check php artisan migrate:status to see which migrations have and have not run.

Check 4: Is the migration in the right package?

Package migrations are in packages/{Package}/database/migrations/. Make sure your migration is in the correct package directory.

Permission checks are not working

Check 1: Did you run permission discovery?

php artisan permissions:discover --path=packages/iam/src/Models --namespace=Exowpee\\IAM\\Models --guard=api

If a permission does not exist in the database, all checks for it will fail.

Check 2: Is the permission assigned to a role?

A permission existing is not enough — it must be assigned to a Role, which must be assigned to a Profile, which must be linked to the user via a UserProfile.

Check 3: Are you checking the Profile or the User?

// WRONG — user-level check
$user->hasPermissionTo('products.create');

// CORRECT — profile-level check (company-scoped)
auth()->profile()?->hasPermissionTo('products.create');

Check 4: Is the guard correct?

Permissions are guard-scoped. A permission on the api guard will not be found when checking via the agent guard.

Tests are failing

Check 1: Is the test database set up?

Nothing to migrate by hand. --parallel creates and migrates <DB_DATABASE>_test_<N> for each process; add --recreate-databases to rebuild them:

docker compose exec app php artisan test --parallel --processes=1 --recreate-databases --filter=Catalog

Do not run php artisan migrate --env=testing inside the app container: env_file exports DB_DATABASE from .env, so it would migrate the development database.

Check 2: Are you running tests for the right package?

# Run tests for a specific package
docker compose exec app php artisan test --parallel --processes=1 --filter=Catalog

Check 3: Is there leftover state from a previous test?

If a test does not use RefreshDatabase or DatabaseTransactions, data from previous tests may leak through.

Using Telescope for debugging

Laravel Telescope is available in local development:

http://localhost:8000/telescope

It is only active when APP_ENV=local.

What to look for

Tab	What it shows	When to use
Requests	All HTTP requests with status codes	Debugging 4xx/5xx errors
Queries	All database queries with timing	Finding N+1 queries, slow queries (>100ms)
Jobs	Queued jobs with status	Debugging failed jobs (WebSocket events, emails)
Events	All dispatched events	Verifying broadcasts (ClientRefresh, OrderStatusUpdated)
Exceptions	Unhandled exceptions with stack traces	Debugging 500 errors
Logs	Application log entries	General debugging

Clearing Telescope data

php artisan telescope:clear

Configuration

Telescope config is in config/telescope.php:

'enabled' => env('TELESCOPE_ENABLED', env('APP_ENV') === 'local'),
'pruning' => ['hours' => 24],

Production debugging

Telescope is disabled in production. For production issues:

Check application logs in storage/logs/
Monitor failed jobs: php artisan queue:failed
Use PostgreSQL query logging for database issues

​I got a 403 Forbidden

​Check 1: Does the user’s profile have the required permission?

​Check 2: Is the policy checking the right thing?

​Check 3: Is the company context correct?

​Check 4: Is this an agent trying to access a user-only endpoint?

​I got a 422 Validation Error

​Check 1: Read the error response

​Check 2: Find the FormRequest class

​Check 3: Check for authorization failures in FormRequest

​Data is not showing up

​Check 1: Are you in the right company context?

​Check 2: Is the data organization-scoped or company-scoped?

​Check 3: Was the record soft-deleted?

​Check 4: Check pagination

​WebSocket events are not working

​Check 1: Is Laravel Reverb running?

​Check 2: Is the queue worker running?

​Check 3: Is the client connecting to the right channel?

​Check 4: Is channel authorization working?

​Migration failed

​Check 1: Is the database accessible?

​Check 2: Does the migration have a dependency on another migration?

​Check 3: Is there a conflicting migration?

​Check 4: Is the migration in the right package?

​Permission checks are not working

​Check 1: Did you run permission discovery?

​Check 2: Is the permission assigned to a role?

​Check 3: Are you checking the Profile or the User?

​Check 4: Is the guard correct?

​Tests are failing

​Check 1: Is the test database set up?

​Check 2: Are you running tests for the right package?

​Check 3: Is there leftover state from a previous test?

​Using Telescope for debugging

​What to look for

​Clearing Telescope data

​Configuration

​Production debugging