# 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](../../platform/hosts/health.md) tab for resource pressure and the recent deploys in [History](../../platform/hosts/revisions.md) 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](../../platform/hosts/services.md). |
| 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](../../platform/hosts/health.md) 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](../../platform/support.md). |
| Slow UI / timeouts under load | OPcache/Redis off or MySQL undersized | Enable OPcache and Redis; review [Best practices](best-practices.md) and [Performance tuning](../../concepts/performance-tuning.md). |

## A troubleshooting workflow

1. Check the host's [Health](../../platform/hosts/health.md) 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](../../platform/hosts/revisions.md); if a recent change broke it, revert and re-publish from [Publishing](../../platform/hosts/publishing.md).
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](../../platform/support.md). The general [platform troubleshooting](../../platform/troubleshooting.md) guide covers issues that are not specific to Akeneo.

## Related

- [Deploy Akeneo](deploy.md)
- [Akeneo best practices](best-practices.md)
- [Health](../../platform/hosts/health.md)
- [Support](../../platform/support.md)