Troubleshooting¶
This document provides comprehensive troubleshooting guidance for common issues encountered during development, deployment, and operation of the Stratpoint Timesheet Application.
Development Environment Issues¶
PHP/Laravel Issues¶
Composer Dependencies¶
Problem: Composer install fails with dependency conflicts
Solution:
# Clear composer cache
composer clear-cache
# Update composer to latest version
composer self-update
# Install with specific PHP version
composer install --ignore-platform-reqs
# Force update if needed
composer update --with-dependencies
Database Connection Issues¶
Problem: Database connection refused
Solutions:
# Check MySQL service status
sudo systemctl status mysql
# Start MySQL service
sudo systemctl start mysql
# Verify database credentials in .env
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=stratpoint_timesheet
DB_USERNAME=your_username
DB_PASSWORD=your_password
# Test connection
php artisan tinker
>>> DB::connection()->getPdo();
Migration Issues¶
Problem: Migration fails with foreign key constraints
Solutions:
# Reset database and run fresh migrations
php artisan migrate:fresh --seed
# Disable foreign key checks temporarily
php artisan tinker
>>> DB::statement('SET FOREIGN_KEY_CHECKS=0;');
>>> Artisan::call('migrate:fresh');
>>> DB::statement('SET FOREIGN_KEY_CHECKS=1;');
# Check migration order in database/migrations
ls -la database/migrations/
Queue Worker Issues¶
Problem: Queue jobs not processing
# Check queue status
php artisan queue:work --verbose
# Common issues and solutions:
# 1. Redis connection issues
redis-cli ping
# Should return PONG
# 2. Failed jobs
php artisan queue:failed
php artisan queue:retry all
# 3. Clear queue cache
php artisan queue:clear
php artisan config:clear
Frontend Issues¶
Node.js/NPM Issues¶
Problem: NPM install fails with permission errors
Solutions:
# Use node version manager
nvm install 18
nvm use 18
# Fix npm permissions
sudo chown -R $(whoami) ~/.npm
sudo chown -R $(whoami) /usr/local/lib/node_modules
# Use yarn instead
npm install -g yarn
yarn install
Build Issues¶
Problem: Asset compilation fails
Solutions:
# Clear node modules and reinstall
rm -rf node_modules package-lock.json
npm install
# Clear Laravel Mix cache
rm -rf public/mix-manifest.json
npm run dev
# Check for missing dependencies
npm audit fix
AngularJS Issues¶
Problem: AngularJS module not found
Solutions:
// Check module dependencies
angular.module('timesheet', [
'ui.router',
'ngResource',
'ngAnimate'
]);
// Verify script loading order in HTML
<script src="angular.js"></script>
<script src="ui-router.js"></script>
<script src="app.js"></script>
<script src="controllers.js"></script>
// Check for circular dependencies
// Use browser dev tools to debug
Production Environment Issues¶
Performance Issues¶
Slow Database Queries¶
Problem: Application responds slowly
# Enable query logging
DB_LOG_QUERIES=true
# Check slow query log
tail -f /var/log/mysql/slow.log
# Analyze queries
php artisan telescope:install
Solutions:
-- Add missing indexes
CREATE INDEX idx_timelogs_user_date ON timelogs(user_id, log_date);
CREATE INDEX idx_timelogs_project_date ON timelogs(project_id, log_date);
-- Optimize queries
EXPLAIN SELECT * FROM timelogs WHERE user_id = 1 AND log_date >= '2024-01-01';
-- Update table statistics
ANALYZE TABLE timelogs;
OPTIMIZE TABLE timelogs;
Memory Issues¶
Problem: PHP memory limit exceeded
Solutions:
# Increase PHP memory limit
echo "memory_limit = 512M" >> /etc/php/8.1/fpm/php.ini
# Optimize Laravel configuration
php artisan config:cache
php artisan route:cache
php artisan view:cache
# Use chunking for large datasets
User::chunk(1000, function ($users) {
foreach ($users as $user) {
// Process user
}
});
Authentication Issues¶
JWT Token Problems¶
Problem: JWT tokens not working
Solutions:
# Check JWT configuration
php artisan jwt:secret
# Verify token in .env
JWT_SECRET=your_secret_key
JWT_TTL=60
# Debug token issues
php artisan tinker
>>> $token = JWTAuth::attempt(['email' => 'test@example.com', 'password' => 'password']);
>>> $user = JWTAuth::parseToken()->authenticate();
Session Issues¶
Problem: Users getting logged out frequently
# Check session configuration
SESSION_DRIVER=redis
SESSION_LIFETIME=120
# Verify Redis connection
redis-cli ping
# Clear sessions
php artisan session:clear
API Issues¶
CORS Problems¶
Problem: Cross-origin requests blocked
Solutions:
// config/cors.php
return [
'paths' => ['api/*', 'sanctum/csrf-cookie'],
'allowed_methods' => ['*'],
'allowed_origins' => ['http://localhost:3000', 'https://timesheet.stratpoint.com'],
'allowed_origins_patterns' => [],
'allowed_headers' => ['*'],
'exposed_headers' => [],
'max_age' => 0,
'supports_credentials' => true,
];
Rate Limiting Issues¶
Problem: API requests being throttled
Solutions:
// app/Http/Kernel.php
'api' => [
'throttle:api',
\Illuminate\Routing\Middleware\SubstituteBindings::class,
],
// Increase rate limits
'throttle:120,1' // 120 requests per minute
// Custom rate limiting
RateLimiter::for('api', function (Request $request) {
return Limit::perMinute(1000)->by($request->user()?->id ?: $request->ip());
});
Database Issues¶
Connection Pool Exhaustion¶
Problem: Too many database connections
Solutions:
-- Check current connections
SHOW PROCESSLIST;
SHOW STATUS LIKE 'Threads_connected';
-- Increase max connections
SET GLOBAL max_connections = 500;
-- Kill idle connections
SELECT CONCAT('KILL ', id, ';') FROM information_schema.processlist
WHERE command = 'Sleep' AND time > 300;
Deadlock Issues¶
Problem: Database deadlocks occurring
Solutions:
// Use database transactions with retry logic
DB::transaction(function () {
// Your database operations
}, 3); // Retry 3 times
// Implement deadlock retry in service
public function updateTimesheet($id, $data)
{
$maxRetries = 3;
$attempt = 0;
while ($attempt < $maxRetries) {
try {
return DB::transaction(function () use ($id, $data) {
return Timesheet::lockForUpdate()->find($id)->update($data);
});
} catch (QueryException $e) {
if ($e->getCode() === '40001' && $attempt < $maxRetries - 1) {
$attempt++;
usleep(rand(100000, 500000)); // Random delay
continue;
}
throw $e;
}
}
}
Cache Issues¶
Redis Connection Problems¶
Problem: Redis connection failures
Solutions:
# Check Redis status
sudo systemctl status redis
# Start Redis
sudo systemctl start redis
# Test connection
redis-cli ping
# Check Redis configuration
cat /etc/redis/redis.conf | grep bind
cat /etc/redis/redis.conf | grep port
# Clear Redis cache
redis-cli FLUSHALL
Cache Invalidation Issues¶
Problem: Stale cache data
# Clear all caches
php artisan cache:clear
php artisan config:clear
php artisan route:clear
php artisan view:clear
# Clear specific cache tags
Cache::tags(['users', 'timesheets'])->flush();
# Disable cache during debugging
CACHE_DRIVER=array
File Permission Issues¶
Storage Permission Problems¶
Problem: Cannot write to storage directory
Solutions:
# Fix storage permissions
sudo chown -R www-data:www-data storage/
sudo chmod -R 775 storage/
# Fix bootstrap cache permissions
sudo chown -R www-data:www-data bootstrap/cache/
sudo chmod -R 775 bootstrap/cache/
# SELinux issues (if applicable)
sudo setsebool -P httpd_can_network_connect 1
sudo chcon -R -t httpd_exec_t storage/
Debugging Tools and Techniques¶
Laravel Debugging¶
// Enable debug mode
APP_DEBUG=true
APP_LOG_LEVEL=debug
// Use Laravel Telescope
composer require laravel/telescope
php artisan telescope:install
php artisan migrate
// Debug queries
DB::enableQueryLog();
// Your code here
dd(DB::getQueryLog());
// Use dump and die
dd($variable);
dump($variable);
// Log debugging information
Log::debug('User login attempt', ['user_id' => $user->id]);
Log::info('Timesheet created', ['timesheet_id' => $timesheet->id]);
Frontend Debugging¶
// Browser console debugging
console.log('Debug info:', data);
console.table(users);
console.group('API Calls');
console.log('Request:', request);
console.log('Response:', response);
console.groupEnd();
// AngularJS debugging
angular.element(document.body).injector().get('$rootScope').$apply();
// Check for scope issues
angular.element('#element').scope();
// Network debugging
// Use browser dev tools Network tab
// Check for failed requests, CORS issues, etc.
Log Analysis¶
# Laravel logs
tail -f storage/logs/laravel.log
# Nginx logs
tail -f /var/log/nginx/access.log
tail -f /var/log/nginx/error.log
# MySQL logs
tail -f /var/log/mysql/error.log
tail -f /var/log/mysql/slow.log
# System logs
journalctl -f -u nginx
journalctl -f -u mysql
Common Error Messages¶
HTTP Status Codes¶
- 500 Internal Server Error: Check Laravel logs, often PHP errors
- 404 Not Found: Check routes, verify URL patterns
- 403 Forbidden: Check permissions, authentication
- 422 Unprocessable Entity: Validation errors, check request data
- 429 Too Many Requests: Rate limiting, reduce request frequency
Database Errors¶
- Connection refused: Database service not running
- Access denied: Wrong credentials or permissions
- Table doesn't exist: Run migrations
- Column not found: Check migration files, run fresh migrations
PHP Errors¶
- Class not found: Check autoloader, run
composer dump-autoload - Memory exhausted: Increase memory limit or optimize code
- Maximum execution time: Increase time limit or optimize queries
Getting Help¶
Internal Resources¶
- Team Slack: #timesheet-dev channel
- Documentation: Confluence wiki
- Code Review: GitHub pull requests
- Issue Tracking: Jira tickets
External Resources¶
- Laravel Documentation: https://laravel.com/docs
- AngularJS Documentation: https://docs.angularjs.org
- Stack Overflow: Tag questions appropriately
- GitHub Issues: For package-specific problems
Escalation Process¶
- Level 1: Check this troubleshooting guide
- Level 2: Ask team members in Slack
- Level 3: Create Jira ticket with details
- Level 4: Escalate to senior developers
- Level 5: Contact DevOps/Infrastructure team
Remember to always include relevant error messages, logs, and steps to reproduce when seeking help.