Troubleshooting

Installation Issues

Composer Authentication Failed

Problem: Authentication fails when installing from anystack.sh

Solution:

  1. Verify your anystack.sh license credentials:

    • Username: Your email address registered with anystack.sh
    • Password: Your license key from anystack.sh

  2. For fingerprinted licenses:

    Password: your-license-key:your-fingerprint

Table Repeater Styles Missing

Problem: Column and filter builders look broken or unstyled

Solution:

  1. Ensure you have a custom Filament theme
  2. Add to your theme CSS: 
    @import '../../../../vendor/awcodes/filament-table-repeater/resources/css/plugin.css';
  3. Update tailwind.config.js: 
    content: [
    './vendor/awcodes/filament-table-repeater/resources/**/*.blade.php',
]
  4. Rebuild your assets: 
    npm run build

Plugin Not Appearing

Problem: Data Lens doesn't show in Filament navigation

Solution:

  1. Clear all caches:

    php artisan cache:clear
php artisan config:clear
php artisan view:clear

  2. Verify plugin registration:

    use Padmission\DataLens\DataLensPlugin;

->plugins([
    DataLensPlugin::make(),
])

  3. Check navigation visibility:

    DataLensPlugin::make()
    ->shouldRegisterNavigation(true)

Configuration Issues

Multi-Tenant Data Leakage

Problem: Users see data from other tenants

Solution:

  1. Enable tenant awareness in config before migrations:

    'tenant_aware' => true,

  2. Verify tenant foreign key exists in database tables

  3. Verify tenant is properly detected in your application

  4. If using custom tenant resolution, configure it in the cache settings:

    // config/data-lens.php
'cache' => [
    'tenant_resolver' => function () {
        return auth()->user()?->team_id;
        // or however you determine tenant in your app
    },
],

Excluded Columns Still Appearing

Problem: Sensitive columns show in report builder

Solution:

  1. Run the detection command:

    php artisan data-lens:suggest-excluded-columns --format=config

  2. Update config with suggestions:

    'excluded_columns' => [
    'global' => ['password', 'api_token'],
    'models' => [
        User::class => ['ssn'],
    ],
],

  3. Clear cache:

    php artisan data-lens:clear-cache

Performance Issues

Slow Report Loading

Problem: Reports take too long to generate

Solution:

  1. Enable caching:

    DATA_LENS_CACHE_ENABLED=true

  2. Add database indexes on filtered columns:

    CREATE INDEX idx_orders_created_at ON orders(created_at);
CREATE INDEX idx_orders_status ON orders(status);

  3. Optimize through relationships:

    'through_relationships' => [
    'optimize_queries' => true,
    'performance_threshold_ms' => 500,
],

Export Timeouts

Problem: Large exports fail or timeout

Solution:

  1. Enable queued exports in config/data-lens.php:

    'exports' => [
    'should_queue' => true,
],

  2. Increase timeout and chunk size:

    DATA_LENS_EXPORT_TIMEOUT=1800
DATA_LENS_EXPORT_CHUNK_SIZE=5000

  3. Ensure queue workers are running:

    php artisan queue:work

API Issues

403 Forbidden Error

Problem: API requests return 403 Forbidden

Solution:

  1. Check IP whitelisting in config/data-lens.php:

    'api' => [
    'ip_whitelist' => ['your.ip.address'],
],

  2. Verify API is enabled for the report:

    • Navigate to report settings
    • Enable API access
    • Generate API key

  3. Check authentication method is correct

Report Not Found via API

Problem: 404 error when accessing report via API

Solution:

  1. Verify using correct UUID (not ID)

  2. Check API is enabled for report:

    SELECT api_uuid, settings->>'$.api.enabled' 
FROM custom_reports 
WHERE name = 'Your Report';

  3. Ensure report exists and user has access

Scheduling Issues

Scheduled Reports Not Sending

Problem: Reports don't run at scheduled times

Solution:

  1. Verify Laravel scheduler is running:

    * * * * * cd /your-project && php artisan schedule:run

  2. Add Data Lens command to scheduler:

    Schedule::command('data-lens:check-scheduled-reports')->everyMinute();

  3. Check for errors:

    php artisan data-lens:check-scheduled-reports --debug

  4. Verify email configuration:

    MAIL_MAILER=smtp
MAIL_FROM_ADDRESS=noreply@example.com

Attachment Size Errors

Problem: Email reports fail with attachment too large

Solution:

  1. Configure max attachment size:

    'scheduling' => [
    'max_attachment_size' => 5120, // 5MB in KB
],

  2. Large reports will automatically use download links instead

Cache Issues

Stale Data After Model Changes

Problem: New fields don't appear after database changes

Solution:

  1. Clear all Data Lens cache:

    php artisan data-lens:clear-cache --force

  2. Clear specific cache type:

    php artisan data-lens:clear-cache --type=model_fields

  3. For multi-tenant apps, ensure cache is cleared for all tenants

Cache Driver Warnings

Problem: Warning about cache driver not supporting tags

Solution:

  1. Use Redis or another tagging-supported driver for production
  2. Accept that all cache will be cleared when using file/database drivers
  3. Configure cache driver: 
    CACHE_DRIVER=redis

Common Error Messages

"Relationship class could not be determined"

Cause: Invalid relationship path or excluded relationship

Fix:

  • Check relationship exists in model
  • Verify not in excluded_relationships config
  • Ensure proper relationship naming

"Column type could not be resolved"

Cause: Unknown database column type

Fix:

  • Check column exists in database
  • Verify column isn't in excluded_columns
  • Clear cache and retry

"Export file not found"

Cause: Export job failed or file was cleaned up

Fix:

  • Check Laravel logs for export errors
  • Verify storage disk permissions
  • Ensure queue workers are running

Debug Mode

Enable detailed logging for troubleshooting:

  1. Set environment variables:

    APP_DEBUG=true
LOG_LEVEL=debug

  2. Run commands with debug flag:

    php artisan data-lens:check-scheduled-reports --debug

  3. Check logs:

    tail -f storage/logs/laravel.log

Getting Help

If issues persist:

  1. Gather information:

    • PHP version: php -v
    • Laravel version: php artisan --version
    • Filament version: composer show filament/filament
    • Data Lens version: composer show padmission/data-lens
    • Error messages and stack traces

  2. Check for updates:

    composer update padmission/data-lens

  3. Contact support: