Magento 2 stack traces: the five lines that actually matter

It is 21:30 on a Thursday. You pushed a release at 17:00, the smoke tests passed, and the catalog team went home. Then a support ticket lands: "Can't save categories anymore." You SSH in, tail var/log/exception.log, and a sixty-line stack trace fills the terminal. Generated proxies, interceptors, framework plumbing. Somewhere in that wall is one call that broke. Finding it should take thirty seconds, not thirty minutes.

Magento 2 traces look intimidating because the framework wraps almost every public method in a chain of generated classes: plugins, interceptors, proxies, factories, lazy loaders. The good news is you can ignore most of it. Five lines do the work.

Line 1: the exception class and the file it was thrown in

The top line tells you two things: what the framework calls the failure, and the file:line where someone explicitly called throw. Read it literally. If the message says "Could not save category", it means a save failed. The file path tells you whose code decided to give up.

exception 'Magento\Framework\Exception\LocalizedException' with message 'Could not save category'
in /var/www/html/vendor/magento/module-catalog/Model/CategoryRepository.php:235

You now know the symptom: core catalog code, line 235, generic "save failed" surface. The cause is further down. Three exception classes you will see again and again: LocalizedException (user-facing, often re-thrown over something else), NoSuchEntityException (a lookup failed), CouldNotSaveException (the persistence layer refused the write). Each one is a hint about which layer to inspect next.

Line 2: the first vendor frame that is not generated code

Just below the exception, the stack opens. The top few frames are almost always generated wrappers. Anything in /generated/code/, anything ending in \Interceptor, anything ending in \Proxy. Skip them. The first frame that lives directly in vendor/magento/ is the real method that ran when the exception was thrown.

#0 /var/www/html/generated/code/.../Interceptor.php(91): Magento\Catalog\Model\CategoryRepository->save()
#1 /var/www/html/vendor/magento/module-catalog/Model/CategoryRepository.php(232): Magento\Catalog\Model\CategoryRepository->validateCategory()

Frame #1 is the throw site. Magento's plugin system means an Interceptor almost always sits between your call and the real method. That is not noise, but it is not the bug either. The bug is whatever the real method tried to do.

Line 3: the first frame from app/code or a third-party vendor

Keep reading down. Skip vendor/magento/ frames, skip the generated proxies. Stop at the first line that points to either app/code/ or vendor/<not-magento>/. That is your suspect.

#7 /var/www/html/vendor/acme/module-catalog-sync/Plugin/CategoryRepositoryPlugin.php(58):
    Magento\Catalog\Model\CategoryRepository\Interceptor->save()

In nine out of ten production incidents, this is the frame you ship to the responsible engineer. A plugin that mutated arguments. An observer that hit an external service in the middle of a transaction. A preference that overrode a core method and forgot a return. The Adobe Commerce docs explain how plugins wrap calls (see the plugins reference), and that wrapping is where most surprise bugs live.

Line 4: the entry point at the bottom

Now jump to the bottom of the trace. The last numbered frame tells you which area of Magento dispatched the request. This matters because the same exception means different things in different contexts.

#42 /var/www/html/pub/index.php(40): Magento\Framework\App\Bootstrap::run()

A few patterns worth recognising on sight:

• pub/index.php: HTTP request, storefront or admin. The controller is earlier in the trace.
• bin/magento: CLI command. Often a deploy, import, or indexer reindex.
• pub/cron.php or a cron group entry: scheduled job, possibly from a different process pool.
• pub/static.php: static-content deploy.
• Magento\Framework\App\Cron::launch: cron entry into the application. Check var/log/cron.log for the schedule.

"Could not save category" thrown from cron is a different problem than one thrown from the admin. Cron runs as a different user, often with a reduced environment, and tends to lose races to other workers.

Line 5: the previous exception

Below the main trace, Magento often appends a chained exception. PHP has supported exception chaining since 5.3 (the Throwable interface exposes getPrevious()), and Magento uses it generously. The framework catches a low-level error, wraps it in a friendlier class, and re-throws. The original cause sits in the "previous" block.

Caused by: PDOException: SQLSTATE[23000]: Integrity constraint violation:
  1062 Duplicate entry '142-3' for key 'CATALOG_CATEGORY_PRODUCT_CATEGORY_ID_PRODUCT_ID'

This is the most useful line on a quiet night. The top of the trace said "Could not save category", which is a generic Magento sentence. The previous exception says: you tried to insert a duplicate row in catalog_category_product. That is no longer a Magento bug. That is a data integrity question, probably a plugin trying to re-link a product that is already linked.

A walked example

Take the trace above and read it as one sentence. Top: catalog category save failed. Throw site: CategoryRepository, line 235. Suspect: acme/module-catalog-sync, plugin on save(). Entry point: pub/index.php, so this is the admin saving a category. Previous: duplicate row in catalog_category_product.

In thirty seconds you have a one-line ticket: "Acme catalog sync plugin double-links products on category save in admin; integrity constraint violation on catalog_category_product." A junior engineer can take that and reproduce locally. You did not have to read forty frames of interceptors.

The thirty-second method

Train yourself to look at five lines in this order: top exception, first vendor frame that is not generated, first app/code or non-Magento vendor frame, bottom entry point, previous exception. Ignore everything else on the first pass.

When we rebuilt a legacy catalog importer for a Dutch retailer on Magento 2.4.7, exception.log was the daily diagnostic. The five-line method is how the team triaged forty exceptions a day down to the three that actually mattered, and it is the same lens we apply on every Magento 2 legacy migration we take on.

Open the most recent exception.log on your own store right now. Find the five lines. Write the one-line ticket. If you cannot, the missing line tells you which part of your Magento mental model needs filling in first.