BDM Documentation

Documentation Troubleshooting Guide

Troubleshooting Guide

Solutions to common issues, error messages, and performance problems in BDM Plain CRM.

Quick Issue Navigator

Installation Login Issues Database API Issues Performance Data Issues Integrations Get Help

Installation Issues

License Validation Errors

Error: "License not found or expired"

The system cannot validate your BDM Plain CRM license.

Solutions:
  • Check your license key in the BDM Hub dashboard
  • Ensure your license hasn't expired
  • Verify internet connectivity for license validation
  • Contact support if license appears valid but still fails

Error: "Plugin not activated"

BDM Plain CRM plugin is installed but not activated.

Solutions:
  • Go to BDM Hub → My Plugins
  • Click "Activate" next to BDM Plain CRM
  • Follow the setup wizard
  • Ensure all required dependencies are installed

Database Migration Issues

SQLSTATE[42000]: Syntax error or access denied
Common Causes & Solutions:
  • Insufficient database permissions: Ensure your database user has CREATE, ALTER, and DROP privileges
  • MySQL version compatibility: BDM Plain CRM requires MySQL 5.7+ or MariaDB 10.3+
  • Character set issues: Ensure database uses UTF8MB4 character set
  • Table prefix conflicts: Check for existing tables with similar names

PHP Requirements Issues

Required PHP Extensions

  • • PDO (for database connections)
  • • cURL (for API requests)
  • • JSON (for data processing)
  • • OpenSSL (for encryption)
  • • Mbstring (for string handling)
  • • XML (for data parsing)

Memory & Execution

  • • PHP 7.4+ (recommended: PHP 8.1)
  • • Memory limit: 256MB minimum
  • • Max execution time: 300 seconds
  • • Upload file size: 64MB+
  • • Post max size: 64MB+

Login and Access Issues

Cannot Access CRM Dashboard

Error: "Access denied" or 404 errors

Check these items:
  1. Ensure you're logged into BDM Hub first
  2. Verify BDM Plain CRM license is active
  3. Check URL: should be /plugins/bdm-plain-crm
  4. Clear browser cache and cookies
  5. Try accessing in incognito/private mode

Redirect loops or session issues

Solutions:
  • Clear all cookies for your domain
  • Check session configuration in Laravel
  • Verify APP_URL in .env matches your domain
  • Ensure proper HTTPS configuration if using SSL

Permission and Role Issues

Note: BDM Plain CRM uses user-based data isolation. Each user only sees their own CRM data.

Common Permission Issues:
  • Empty dashboard: User may need to complete initial setup or add first contacts
  • Missing menu items: Check if user has proper license access
  • Cannot create records: Verify user has active license and database permissions
  • API access denied: Ensure user has generated API keys in settings

Database Errors

Database Connection Issues

SQLSTATE[HY000] [2002] No connection could be made

Immediate Checks

  1. Verify database server is running
  2. Check .env database credentials
  3. Test connection with database client
  4. Verify firewall settings
  5. Check database server logs

Common .env Issues

  • DB_HOST incorrect (try 127.0.0.1 vs localhost)
  • DB_PORT wrong (default: 3306)
  • DB_DATABASE name typo
  • DB_USERNAME/DB_PASSWORD incorrect
  • Missing quotes around special characters

SQL Query Errors

Table doesn't exist errors

Solutions:
  1. Run migrations: php artisan migrate
  2. Check if migrations completed successfully
  3. Verify table prefix in database.php config
  4. Manually check database for expected tables

Column not found errors

Usually caused by:
  • Incomplete migrations - run pending migrations
  • Database out of sync - check migration status
  • Custom modifications that broke schema
  • Version mismatch between code and database

Database Performance Issues

Slow Queries

  • • Enable slow query log
  • • Check for missing indexes
  • • Optimize large datasets
  • • Consider database caching
  • • Review complex joins

Connection Limits

  • • Monitor active connections
  • • Increase max_connections if needed
  • • Implement connection pooling
  • • Check for connection leaks
  • • Optimize query execution time

API Issues

API Authentication Errors

401 Unauthorized errors

Check these items:
  1. API key format: Bearer bdm_crm_your_key
  2. Verify API key is active and not expired
  3. Check API key permissions and domain restrictions
  4. Ensure key belongs to correct user account
  5. Test with a newly generated API key

403 Forbidden errors

Common causes:
  • API key domain restrictions don't match request origin
  • API key permissions insufficient for requested action
  • User account suspended or inactive
  • Rate limit exceeded for API key

Rate Limiting Issues

Default Limit: 1000 requests per hour per API key

When you hit rate limits:
  • Monitor X-RateLimit-Remaining header
  • Implement exponential backoff in your code
  • Cache API responses where possible
  • Use batch operations for multiple records
  • Consider upgrading to higher limits if needed

Webhook and Integration Issues

Webhook Failures

  • • Check webhook URL accessibility
  • • Verify SSL certificate validity
  • • Review webhook payload format
  • • Monitor webhook response codes
  • • Check for timeout issues

BDM App Integration

  • • Ensure both apps are updated
  • • Check integration permissions
  • • Verify API key configuration
  • • Review error logs in both apps
  • • Test integration with simple data

Performance Issues

Slow Page Loading

Server-Side Optimization

  • • Enable Laravel caching (config, views, routes)
  • • Optimize database queries and indexes
  • • Enable OPcache for PHP
  • • Configure Redis or Memcached
  • • Optimize Composer autoloader
  • • Review slow query logs

Browser-Side Issues

  • • Clear browser cache and cookies
  • • Disable browser extensions temporarily
  • • Check browser developer tools for errors
  • • Test in different browsers
  • • Verify internet connection speed
  • • Check for JavaScript console errors

Large Dataset Performance

Performance Tip: BDM Plain CRM is optimized for up to 100,000 contacts per user. Larger datasets may require additional optimization.

Optimization strategies:
  • Use pagination for large contact lists
  • Implement search filters to reduce result sets
  • Archive old or inactive records
  • Enable database query caching
  • Consider data archiving for historical records
  • Use API pagination for large data exports

Memory and Resource Issues

Fatal error: Memory limit exceeded

Solutions:
  1. Increase PHP memory_limit to 512MB or higher
  2. Optimize data processing to use less memory
  3. Use database chunking for large operations
  4. Enable PHP garbage collection

Script timeout errors

Common fixes:
  • Increase max_execution_time for imports/exports
  • Use background job queues for heavy operations
  • Break large operations into smaller chunks
  • Optimize database queries to run faster

Data Issues

Import/Export Problems

CSV import failures

Common issues and fixes:
  • Encoding problems: Ensure CSV is UTF-8 encoded
  • Column mapping: Verify column headers match expected format
  • Data validation: Check for invalid email formats or phone numbers
  • File size: Large files may need to be split into smaller chunks
  • Required fields: Ensure first_name and last_name are present

Export timeouts or incomplete data

Solutions:
  • Use filters to reduce dataset size
  • Export in smaller date ranges
  • Try exporting specific record types
  • Use API for programmatic large exports

Data Integrity Issues

Warning: Always backup your database before attempting data repair operations.

Missing or Corrupted Records

  • • Check database foreign key constraints
  • • Review recent data changes or imports
  • • Verify user permissions and data isolation
  • • Check for soft-deleted records
  • • Review activity logs for clues

Duplicate Records

  • • Use search to identify duplicates
  • • Check import logs for duplicate entries
  • • Review data validation rules
  • • Consider implementing duplicate detection
  • • Merge records manually if needed

Search and Filtering Issues

Search returns no results

  • Check for typos in search terms
  • Try partial search terms or wildcards
  • Verify data exists and user has access
  • Clear search filters that might be too restrictive

Slow search performance

  • Use more specific search terms
  • Apply filters before searching
  • Check database indexes on searchable fields
  • Consider search result pagination

Integration Problems

BDM App Integration Issues

BDM Mailer Integration

  • Contacts not syncing: Check API permissions
  • Email activities missing: Verify webhook setup
  • Segmentation issues: Review contact status mapping
  • Campaign tracking: Ensure activity logging is enabled

BDM Accounting Integration

  • Customer data sync: Verify contact-to-customer mapping
  • Invoice tracking: Check webhook configuration
  • Missing transactions: Review API call logs
  • Data format issues: Validate address and tax fields

Third-party Integration Issues

Webhook delivery failures

Troubleshooting steps:
  1. Test webhook URL manually with curl or Postman
  2. Check for SSL certificate issues
  3. Verify webhook URL is publicly accessible
  4. Review webhook response time (should be under 10 seconds)
  5. Check for authentication requirements

API response format issues

Common problems:
  • Unexpected JSON structure in responses
  • Missing or renamed fields after updates
  • Date format inconsistencies
  • Pagination parameter changes

Getting Help

Support Channels

Email Support

Get help via email with detailed responses

support@bdmhub.com

Documentation

Comprehensive guides and references

View Documentation

Community

Connect with other BDM users

Coming Soon

What to Include in Support Requests

System Information

  • • BDM Hub version and CRM plugin version
  • • PHP version and server environment
  • • Database type and version
  • • Browser and version (for UI issues)
  • • Operating system

Issue Details

  • • Detailed description of the problem
  • • Steps to reproduce the issue
  • • Expected vs actual behavior
  • • Error messages or codes
  • • Screenshots or screen recordings

Tip: The more detailed information you provide, the faster we can help resolve your issue. Please never include passwords or sensitive API keys in support requests.

BDM Plain CRM Troubleshooting Guide v1.0