Troubleshooting

Troubleshooting

Common issues and their solutions when running or developing Bill Organizer.

---

Application Issues

Permission Errors on Storage or Cache

Symptom: file_put_contents(): failed to open stream: Permission denied

chmod -R 775 storage bootstrap/cache
chown -R www-data:www-data storage bootstrap/cache

For local development (macOS / Linux):

chmod -R 775 storage bootstrap/cache

---

Database Not Found / Migration Errors

Symptom: SQLSTATE[HY000] [14] unable to open database file

For SQLite, create the database file first:

touch database/database.sqlite
php artisan migrate

To reset and reseed:

php artisan migrate:fresh --seed

---

Cache / Config Issues

Symptom: Configuration changes not taking effect, stale routes, or view errors.

php artisan optimize:clear

This clears all cached config, routes, views, and compiled files. Then:

php artisan optimize   # Rebuild for production

---

Queue Workers Not Processing Jobs

Symptom: Notifications not sending, webhook deliveries not firing.

# Restart workers
php artisan queue:restart

# Or run a fresh worker manually
php artisan queue:work --verbose

In production, ensure Supervisor is running the worker process. Check logs at storage/logs/worker.log.

---

Mail Not Sending

Symptom: No notification emails arriving.

1. Verify .env mail settings:

   MAIL_MAILER=smtp
   MAIL_HOST=your-smtp-host
   MAIL_PORT=587
   MAIL_USERNAME=your-user
   MAIL_PASSWORD=your-password
   MAIL_ENCRYPTION=tls
   MAIL_FROM_ADDRESS=noreply@yourdomain.com

2. For local development, use MAIL_MAILER=log — emails are written to storage/logs/laravel.log
3. Test mail sending:

   php artisan tinker
   Mail::raw('Test', fn($m) => $m->to('test@example.com')->subject('Test'));

---

API Issues

401 Unauthorized

Cause: Missing or invalid Bearer token.

• Verify the token is present: Authorization: Bearer {token}
• Check the token has not been revoked (the user may have logged out on another device)
• Login again to obtain a fresh token: POST /api/v1/auth/login

---

403 Forbidden — Team Required

Cause: The user has no active team set, or the resource belongs to a different team.

• Switch to the correct team: POST /api/v1/teams/{team}/switch
• Verify the user is a member of the team: GET /api/v1/teams

---

422 Unprocessable Entity

Cause: Request payload failed validation.

• Read the errors field in the response — it lists all failing fields and their error messages
• Cross-reference with the API documentation for required fields and formats

Example response:

{
  "message": "The given data was invalid.",
  "errors": {
    "amount": ["The amount must be at least 0."],
    "due_date": ["The due date field is required."]
  }
}

---

429 Too Many Requests

Cause: Rate limit exceeded.

• Check the X-RateLimit-Reset header — it contains the Unix timestamp when the limit resets
• Wait and retry
• Implement exponential backoff in your client
• Raise the limit in .env if needed:

  API_RATE_LIMIT=120

---

CORS Errors (Browser Clients)

Cause: The frontend origin is not in the CORS allowed list.

• Add your origin to .env:

  CORS_ALLOWED_ORIGINS=https://yourapp.com

• Ensure every request includes Accept: application/json
• Clear config cache: php artisan config:cache

---

Frontend Issues

Vite Build Errors

Symptom: yarn build fails.

• Run TypeScript check first: yarn tsc --noEmit
• Check vite.config.ts for misconfigured aliases or plugins
• Verify all imported packages are installed: yarn install

---

Inertia Page Not Updating

Symptom: Changes to Vue components not reflected after refresh.

# In development — ensure Vite is running
yarn dev

# Hard reload in browser
Ctrl + Shift + R (Windows/Linux) / Cmd + Shift + R (macOS)

---

Ziggy Routes Not Available

Symptom: route() helper returns undefined in Vue components.

php artisan ziggy:generate

This regenerates the Ziggy route file used by the frontend.

---

Docker / Sail Issues

Containers Not Starting

./vendor/bin/sail down --volumes   # Stop and remove volumes
./vendor/bin/sail build            # Rebuild images
./vendor/bin/sail up -d            # Start fresh

Port Already in Use

Update port mappings in .env:

APP_PORT=8080          # Change from default 8500
VITE_PORT=5174         # Change Vite port
FORWARD_DB_PORT=33060  # Change DB port

---

GitHub Actions / Release Issues

Build Fails — TypeScript Errors

Fix type errors locally before pushing:

yarn tsc --noEmit

Wrong Version Generated

Check that existing git tags follow semver format (v1.2.3):

git tag --list | sort -V

Delete a conflicting tag if needed:

git tag -d v1.2.3
git push origin --delete v1.2.3

Workflow Permission Error

Ensure GitHub Actions has write permissions:

1. Go to Settings → Actions → General
2. Under Workflow permissions, select Read and write permissions

---

Getting Help

• Documentation: Browse this wiki
• Logs: php artisan pail (real-time) or storage/logs/laravel.log
• GitHub Issues: github.com/4msar/bill-organizer/issues
• Email: support@bills.msar.me