Debugging production-only issues in Adobe Commerce

Introduction

Debugging Adobe Commerce issues that only occur in production is one of the hardest parts of Magento development. In many real-world projects, merchants work directly in the production admin: updating products, prices, promotions, CMS blocks, and configuration throughout the week. As a result, bugs often depend on live data that cannot be reproduced reliably with an outdated local database.

When staging is regularly synced from production, it becomes a safe and accurate mirror of real-world data. By running Adobe Commerce locally while connecting directly to the staging database through a secure Magento Cloud (MGC) SSH tunnel, developers can reproduce production-only issues quickly and debug them using local tools such as Xdebug.

Overview

The goal is to:

• Run Adobe Commerce locally (often in Docker)

• Connect securely to the staging MySQL database

• Override environment-specific configuration locally

• Debug production-only issues using Xdebug

This workflow is especially useful for:

• Bugs that only occur in production

• Issues driven by real catalog, order, or configuration data

• Projects where merchants primarily operate in production

• Avoiding repeated database dumps and imports

An alternative to database dumps

This approach is a practical alternative to regularly dumping the latest staging or production database into a local environment.

Production data changes constantly. Database dumps become stale very quickly, and re-importing them is slow and disruptive. When merchants work mainly in production, a dump taken even a few days earlier may no longer reflect the state that caused the issue.

By connecting a local instance directly to the staging database, developers can:

• Work with the most up-to-date production-like data

• Avoid exporting and importing large database dumps

• Reproduce bugs immediately after they are reported

• Debug issues that depend on current configuration or content

Instead of copying data locally, the local Magento instance temporarily connects to the remote database via a secure tunnel, leaving the remote environment untouched.

Prerequisites

You will need:

• A local Adobe Commerce codebase

• Access to the staging environment on Magento Cloud

• Magento Cloud CLI (magento-cloud)

• PHP running locally or in Docker

• SSH access enabled for the project

Create the database tunnel

Magento Cloud provides built-in SSH tunnelling to internal services such as MySQL.

magento-cloud tunnel:open -p 30000

This forwards the remote MySQL service to local port 30000. Keep the tunnel running while you work.

Configure Magento to use the tunnel

Database configuration must be defined explicitly in:

app/etc/env.php

Host selection:

• PHP on host → 127.0.0.1

• PHP in Docker → host.docker.internal

<?php
declare(strict_types=1);

return [
    'db' => [
        'connection' => [
            'default' => [
                'host' => 'host.docker.internal',
                'port' => '30000',
                'dbname' => 'staging_db_name',
                'username' => 'staging_db_user',
                'password' => 'staging_db_password',
                'model' => 'mysql4',
                'engine' => 'innodb',
                'active' => '1',
            ],
        ],
    ],
];

Override base URLs locally

<?php
declare(strict_types=1);

return [
    'system' => [
        'default' => [
            'web' => [
                'unsecure' => [
                    'base_url' => 'http://local.magento/',
                ],
                'secure' => [
                    'base_url' => 'http://local.magento/',
                ],
            ],
        ],
    ],
];

Clear caches after changes

rm -rf var/cache/* var/page_cache/* generated/* var/view_preprocessed/*
bin/magento cache:flush

Docker and Xdebug considerations

• Tunnel runs on the host

• PHP container connects via host.docker.internal

• No local MySQL container required

• Xdebug attaches locally from the IDE

Applicability beyond Magento Cloud

The same concept applies to any Magento or Adobe Commerce installation. Without Magento Cloud, use a standard SSH tunnel or VPN instead of MGC.

Security and best practices

• Use staging, never production

• Keep staging in sync with production

• Avoid cron, consumers, and indexers locally

• Do not commit env.php

• Close tunnels when not in use

Conclusion

Running Adobe Commerce locally against a staging database via an MGC tunnel is a highly effective way to debug issues that only surface in production-like conditions. It removes the friction of database dumps, keeps investigations aligned with current merchant data, and enables powerful local debugging with Xdebug. For teams where production is the primary working environment, this workflow often provides the fastest and most reliable path to resolving complex bugs.