Comprehensive troubleshooting guide for Magento 2 performance issues, tracking problems, and common configuration challenges.

Magento Troubleshooting Guide

This guide covers common Magento 2 and Adobe Commerce issues, from Core Web Vitals optimization to analytics tracking problems. Find solutions for performance bottlenecks, configuration errors, and implementation challenges.

Common Issue Categories

Performance Issues

Core Web Vitals:

Largest Contentful Paint (LCP) - Slow page loading, image optimization, caching
Cumulative Layout Shift (CLS) - Layout instability, image dimensions, font loading

General Performance:

Slow page load times
High server response time (TTFB)
JavaScript blocking issues
CSS render blocking

Tracking & Analytics Issues

Events Not Firing - GA4, GTM, Meta Pixel tracking problems
Data layer not populating
Conversion tracking failures
Duplicate event tracking

Configuration Issues

Cache problems (FPC, Varnish, Redis)
Module conflicts
RequireJS errors
KnockoutJS binding issues

Quick Diagnostics

Performance Diagnostics

1. Check Magento Mode

php bin/magento deploy:mode:show

Expected: Production mode for live sites Fix:

php bin/magento deploy:mode:set production

2. Verify Caching Status

php bin/magento cache:status

Expected: All caches enabled Fix:

php bin/magento cache:enable
php bin/magento cache:flush

3. Check Indexers

php bin/magento indexer:status

Expected: All indexes up-to-date Fix:

php bin/magento indexer:reindex

4. Test Full Page Cache

curl -I https://your-store.com/

Look for: X-Magento-Cache-Control: max-age=86400, public, s-maxage=86400

Tracking Diagnostics

1. Check JavaScript Console

Open browser DevTools > Console tab Look for: JavaScript errors, failed network requests

2. Verify Network Requests

DevTools > Network tab Look for: Analytics requests to:

google-analytics.com/collect
googletagmanager.com/gtm.js
facebook.com/tr

3. Test Data Layer

Console:

console.log(window.dataLayer);

Expected: Array with event objects

4. Validate GTM Preview

Enable GTM Preview mode
Visit store
Check Tags Fired tab

Common Error Messages

1. "There has been an error processing your request"

Causes:

Exception in code
Database connection issues
File permissions

Diagnosis:

tail -f var/log/system.log
tail -f var/log/exception.log

Solutions:

Check error logs for specific error
Verify database credentials in app/etc/env.php

Fix file permissions:

find var generated pub/static pub/media app/etc -type f -exec chmod 664 {} \;
find var generated pub/static pub/media app/etc -type d -exec chmod 775 {} \;

2. "The page isn't redirecting properly"

Causes:

Redirect loop in configuration
SSL/HTTPS misconfiguration
Web server rewrite issues

Solutions:

Check base URLs:

php bin/magento config:show web/unsecure/base_url
php bin/magento config:show web/secure/base_url

Verify SSL settings in Admin:

Stores > Configuration > General > Web > Secure

Check .htaccess rewrite rules

3. "404 Error" on Admin Panel

Causes:

Custom admin URL not configured
Web server rewrite issues
Static content deployment missing

Solutions:

Check admin path:
```
php bin/magento info:adminuri
```
Enable rewrites in .htaccess

Deploy static content:

php bin/magento setup:static-content:deploy

Performance Troubleshooting Tools

1. Magento Profiler

Enable built-in profiler:

File: index.php or pub/index.php

\Magento\Framework\Profiler::applyConfig([
    'drivers' => [
        [
            'type' => 'html',
            'output' => ''
        ]
    ]
], BP, false);

2. New Relic APM

Monitor application performance:

Install New Relic PHP agent

Configure in Magento:

php bin/magento config:set newrelicreporting/general/enable 1

3. Blackfire.io

Profile PHP performance:

blackfire curl https://your-store.com/

4. Chrome DevTools

Performance Tab:

Record page load
Analyze waterfall
Identify bottlenecks

Lighthouse:

Run audit (Performance, Accessibility, Best Practices, SEO)
Review recommendations

Caching Issues

Full Page Cache (FPC) Not Working

Symptoms:

Pages always dynamic
No performance improvement
X-Magento-Cache-Control header missing

Solutions:

Enable FPC:

php bin/magento config:set system/full_page_cache/caching_application 1
php bin/magento cache:enable full_page

Check cache type:

Stores > Configuration > Advanced > System > Full Page Cache

Set to "Built-in" or "Varnish"

Verify cache hits:
```
curl -I https://your-store.com/
```
Look for: X-Magento-Cache-Debug: HIT

Varnish Not Caching

Diagnosis:

varnishstat -1 | grep MAIN.cache_hit

Solutions:

Export Varnish VCL:

php bin/magento varnish:vcl:generate --export-version=6 > varnish.vcl

Reload Varnish:
```
systemctl reload varnish
```
Check Varnish config:
```
Stores > Configuration > Advanced > System > Full Page Cache
```
- Caching Application: Varnish
- Backend Host: localhost
- Backend Port: 8080

Redis Issues

Test connection:

redis-cli ping

Expected: PONG

Check Redis stats:

redis-cli info stats

Clear Redis cache:

redis-cli flushall

JavaScript & RequireJS Issues

RequireJS Errors

Common errors:

"Mismatched anonymous define() module"
"Script error for..."
Module load timeout

Solutions:

Clear RequireJS cache:

rm -rf pub/static/frontend/
rm -rf var/view_preprocessed/
php bin/magento setup:static-content:deploy

Disable JS bundling:

php bin/magento config:set dev/js/enable_js_bundling 0

Check requirejs-config.js:
- Verify paths are correct
- Check for circular dependencies
- Ensure shim configurations are valid

KnockoutJS Binding Errors

Error: "Unable to process binding"

Solutions:

Check template syntax:

<!-- Correct -->
<!-- ko if: isVisible -->
<div data-bind="text: message"></div>
<!-- /ko -->

Verify data structure:
- Ensure observables are properly initialized
- Check for undefined variables

Clear generated code:

rm -rf generated/code/
php bin/magento setup:di:compile

Database Issues

Slow Queries

Enable query logging:

File: app/etc/env.php

'db' => [
    'connection' => [
        'default' => [
            'profiler' => [
                'enabled' => 1,
                'class' => '\Magento\Framework\DB\Profiler'
            ]
        ]
    ]
]

Analyze slow queries:

tail -f var/log/db.log

Solutions:

Add indexes to frequently queried columns
Optimize queries
Enable MySQL query cache
Upgrade to Elasticsearch for catalog search

Database Connection Errors

Error: "SQLSTATE[HY000] [2002] Connection refused"

Solutions:

Check MySQL is running:
```
systemctl status mysql
```

Verify credentials: File: app/etc/env.php

'db' => [
    'connection' => [
        'default' => [
            'host' => 'localhost',
            'dbname' => 'magento',
            'username' => 'magento_user',
            'password' => 'password',
            'active' => '1'
        ]
    ]
]

Test connection:

mysql -u magento_user -p -h localhost magento

Elasticsearch Issues

Catalog Search Not Working

Verify Elasticsearch:

curl http://localhost:9200/_cluster/health?pretty

Check Magento configuration:

Stores > Configuration > Catalog > Catalog > Catalog Search

Search Engine: Elasticsearch 7

Reindex catalog:

php bin/magento indexer:reindex catalogsearch_fulltext

Module Conflicts

Identifying Conflicts

Check for duplicate modules:

php bin/magento module:status

Disable problematic module:

php bin/magento module:disable Vendor_Module
php bin/magento setup:upgrade

Check for di.xml conflicts:

Review preference overrides
Check plugin order
Verify class rewrites

Common CLI Commands

Maintenance Mode

# Enable
php bin/magento maintenance:enable

# Disable
php bin/magento maintenance:disable

# Check status
php bin/magento maintenance:status

Cache Management

# Flush cache
php bin/magento cache:flush

# Clean cache
php bin/magento cache:clean

# Disable all caches (for debugging)
php bin/magento cache:disable

Deployment

# Full deployment
php bin/magento setup:upgrade
php bin/magento setup:di:compile
php bin/magento setup:static-content:deploy -f
php bin/magento cache:flush

Getting Help

Magento Logs

Check these log files:

var/log/system.log      # General system logs
var/log/exception.log   # Exception traces
var/log/debug.log       # Debug information
var/report/            # Error reports

Enable Developer Mode

For detailed error messages:

php bin/magento deploy:mode:set developer

Note: Never use developer mode in production!

Community Resources

Magento Stack Exchange - Q&A community
Magento DevDocs - Official documentation
Magento Forums - Community forums
GitHub Issues - Bug tracking

Next Steps

Explore specific troubleshooting guides:

LCP Optimization - Fix slow loading times
CLS Fixes - Resolve layout shifts
Tracking Issues - Debug analytics problems

Prevention Best Practices

Regular Maintenance

Keep Magento Updated:

composer update
php bin/magento setup:upgrade

Monitor Logs:
```
tail -f var/log/*.log
```
Regular Backups:
- Database backups
- Code backups
- Media file backups
Performance Monitoring:
- Use APM tools (New Relic, Datadog)
- Monitor server resources
- Track Core Web Vitals

Development Best Practices

Use version control (Git)
Test in staging before production
Follow Magento coding standards
Use proper dependency injection
Implement comprehensive logging
Write unit and integration tests