Troubleshooting Akeneo

Most Akeneo problems on TurboStack have one of three causes. The job queues may not be running, the search index may be missing or unreachable, or the Symfony cache or permissions may be stale. This page shows where to look and how to fix the common cases.

Where to find the logs

Component	Where
Akeneo application	var/logs/*.log in the app directory (rotated automatically)
Job queues	journalctl --user -u 'pim-job-queue@*' for the queue consumers
Nginx (web)	the host's Nginx access/error logs
PHP-FPM	the PHP-FPM error log for the app's pool
Database	the MySQL error log

Also check the host's Health tab for resource pressure and the recent deploys in History to correlate a problem with a change.

Common issues

Symptom	Likely cause	Fix
Imports/exports start but never finish	One or more job-queue services not running	Confirm pim-job-queue@ui_job, @import_export_job and @data_maintenance_job are active (systemctl --user status 'pim-job-queue@*') and restart them. See Services.
500 errors / blank UI, "no alive nodes" or index errors	Elasticsearch/OpenSearch down or unreachable	Verify the search service is running and reachable at APP_INDEX_HOSTS (default localhost:9200); Akeneo cannot run without it.
Products missing from search/grids	Index out of date or not built	Reindex: bin/console pim:product:index and bin/console pim:product-model:index --env=prod.
Errors after a deploy or upgrade	Stale Symfony cache or assets	Run bin/console cache:clear --env=prod and rebuild with make prod.
"Permission denied" / cannot write cache or logs	var/cache or var/logs owned wrong or full disk	Check ownership of the var/ directory and free disk on the Health tab.
PDF generation or spell-check fails on export	Missing system tool	The platform installs ghostscript and aspell; if a custom export needs another tool (e.g. wkhtmltopdf), contact Support.
Slow UI / timeouts under load	OPcache/Redis off or MySQL undersized	Enable OPcache and Redis; review Best practices and Performance tuning.

A troubleshooting workflow

1. Check the host's Health tab for CPU, memory and disk pressure.
2. Read the relevant log - start with var/logs/*.log, then the job-queue journal for stuck imports/exports.
3. Review the last deploy in History; if a recent change broke it, revert and re-publish from Publishing.
4. Verify the services are running: the three pim-job-queue@* consumers, Elasticsearch/OpenSearch, MySQL and Redis. Restart any that are down and reindex if needed.

Getting help

If you are still stuck, gather the relevant log excerpt and the time the problem started, then reach out via Support. The general platform troubleshooting guide covers issues that are not specific to Akeneo.

Related

• Deploy Akeneo
• Akeneo best practices
• Health
• Support