Menu
Table of Contents

Analytics - v1.3.0

Troubleshooting

This guide covers common issues and their solutions.

Installation Issues

Migration fails with "table already exists"

The analytics tables may already exist from a previous installation.

Solution:

# Check existing tables
php artisan tinker
>>> Schema::hasTable('analytics_page_views')

# If tables exist, you can:
# 1. Skip migrations during install
php artisan analytics:install --skip-migrations

# 2. Or manually drop tables and reinstall
php artisan migrate:rollback --path=vendor/artisanpack-ui/analytics/database/migrations
php artisan migrate

Config file not publishing

Solution:

# Force publish
php artisan vendor:publish --tag=analytics-config --force

# Or manually check
ls config/artisanpack/

Assets not found (404 on analytics.js)

Solution:

# Publish assets
php artisan vendor:publish --tag=analytics-assets --force

# Verify file exists
ls public/js/analytics.js

Tracking Issues

No page views being recorded

Check these in order:

  1. Is analytics enabled?
// .env
ANALYTICS_ENABLED=true
  1. Is the tracking script included?
{{-- Check your layout file --}}
@analyticsScripts
  1. Is the path excluded?
// Check config
'excluded_paths' => ['/admin/*', '/api/*'],

  1. Is the visitor a bot? Check if the user agent matches excluded patterns. Since 1.2.0, visitors may also be flagged by behavioral bot detection and excluded from results by default. Review flagged visitors with php artisan analytics:bots, or whitelist a visitor with php artisan analytics:whitelist.

  2. Is consent required but not given?

'privacy' => ['consent_required' => false], // or check consent

  1. Check browser console for JavaScript errors

  2. Check Laravel logs:

tail -f storage/logs/laravel.log

Events not tracking

Solution:

// Verify tracking works
trackEvent('test_event', ['test' => true]);

// Check events table
Event::latest()->first();

// Check if event name is allowed (if restricted)
'events' => ['allowed_names' => []], // Empty = allow all

Queue jobs not processing

Solution:

# Check if queue worker is running
php artisan queue:work --queue=analytics

# Check failed jobs
php artisan queue:failed

# Retry failed jobs
php artisan queue:retry all

# Check job is dispatched to correct queue
'local' => ['queue_name' => 'analytics'],

Realtime visitors always shows 0

Possible causes:

  1. No recent page views (within last 5 minutes)
  2. Cache issue - clear analytics cache
  3. Database connection issue

Solution:

# Clear cache
php artisan analytics:clear-cache

# Check recent page views
php artisan tinker
>>> PageView::where('created_at', '>=', now()->subMinutes(5))->count()

Dashboard Issues

Dashboard returns 404

Solution:

# Check route is registered
php artisan route:list | grep analytics

# Check middleware (must be authenticated by default)
'dashboard_middleware' => ['web', 'auth'],

# Try accessing while logged in

Dashboard shows no data

Solution:

  1. Check date range - default is last 7 days
  2. Verify data exists:
PageView::count();
Session::count();
  1. Check site filter (multi-tenant):
<livewire:artisanpack-analytics::analytics-dashboard :site-id="null" />
  1. Clear cache:
php artisan analytics:clear-cache

Charts not rendering

Solution:

  1. Ensure Chart.js is loaded:
<script src="https://cdn.jsdelivr.net/npm/chart.js"></script>

  1. Check for JavaScript errors in browser console

  2. Verify chart data:

// In component
dd($this->chartData);

Livewire errors

Common issues:

  1. Component not found:
# Clear view cache
php artisan view:clear
php artisan cache:clear

  1. Alpine.js conflicts: Livewire 3 includes Alpine.js. Don't load it separately.

  2. Component class not found:

composer dump-autoload

Performance Issues

Slow dashboard loading

Solutions:

  1. Increase cache duration:
'dashboard' => ['cache_duration' => 600], // 10 minutes

  1. Reduce date range: Default to shorter periods for initial load.

  2. Check database indexes:

SHOW INDEX FROM analytics_page_views;
  1. Enable query logging to find slow queries:
DB::enableQueryLog();
// ... load dashboard
dd(DB::getQueryLog());

High memory usage

Solutions:

  1. Use queue processing:
'queue_processing' => true,
  1. Reduce retention period:
'retention' => ['period' => 30],
  1. Run cleanup:
php artisan analytics:cleanup

Database growing too fast

Solutions:

  1. Reduce retention:
'retention' => ['period' => 30],
  1. Enable aggregation:
'retention' => ['aggregate_before_delete' => true],
  1. Schedule cleanup:
Schedule::command('analytics:cleanup')->daily();

Multi-Tenant Issues

Site not resolving

Debug steps:

use ArtisanPackUI\Analytics\Services\TenantManager;

$manager = app(TenantManager::class);
$site = $manager->resolveSite(request());
dd($site);

Check:

  1. Is multi-tenant enabled?
'multi_tenant' => ['enabled' => true],
  1. Does the site exist?
Site::where('domain', 'example.com')->first();
  1. Is the resolver configured correctly?

Data mixing between tenants

Solution:

Ensure all queries use site scope:

PageView::forSite($siteId)->get();
// Not: PageView::all();

API key not working

Check:

  1. Is the API key correct?
Site::where('api_key', 'your_key')->first();
  1. Is the header correct?
X-API-Key: your_key
  1. Is query parameter enabled (if using)?
'allow_query_api_key' => true,

Privacy/Consent Issues

Solution:

{{-- Ensure directive is in layout --}}
@analyticsConsentBanner

{{-- Or use component directly --}}
<livewire:artisanpack-analytics::consent-banner />

Check:

// Is consent required?
'privacy' => ['consent_required' => true],

// Check consent status
analyticsHasConsent($fingerprint, 'analytics');

IP not being anonymized

Solution:

'privacy' => [
    'anonymization' => [
        'ip_address' => true,
    ],
],

// Also check local provider setting
'local' => ['anonymize_ip' => true],

Error Messages

"Tracking is disabled"

Analytics is turned off. Enable it:

ANALYTICS_ENABLED=true

"Site not found"

In multi-tenant mode, no site could be resolved. Check:

  • Site exists in database
  • Resolver is correctly configured
  • Request has correct identifiers (API key, domain, etc.)

"Provider not found: xyz"

The provider isn't registered:

// Check active providers
'active_providers' => ['local'], // 'xyz' not included

"Queue connection not configured"

Queue driver isn't set up:

# Check queue config
php artisan queue:work
# If fails, configure queue driver
QUEUE_CONNECTION=database
php artisan queue:table
php artisan migrate

Getting Help

If you can't resolve an issue:

  1. Check the FAQ for common questions
  2. Search existing issues on GitHub
  3. Create a new issue with:
    • Laravel version
    • Package version
    • Error message/logs
    • Steps to reproduce
    • Configuration (sanitized)

Repository: GitHub