Operations & Troubleshooting

Observability

• Horizon dashboard `/horizon` for queue health, failures, and retries.
• Application logs (stack) show Driver logs and job transitions.
• `mutation_jobs` contains status, attempts, last error.
• Activity feed at `/activity` lists events such as webhook receipt, mutation creation, job queueing/processing, successes and failures. Supports simple filtering by type, entity, and free-text search.

Common Checks

• Queues running? `php artisan horizon` in the container.
• Redis reachable? `REDIS_HOST=redis` in `.env` when using Docker.
• DB migrated? `php artisan migrate` and tables exist.
• Integration enabled and configured? Check `integrations` table records and `config/integrations.php`.

SQLSTATE[42S22] Unknown column in SET

• Symptom: `Unknown column 'websites' in 'SET'` when running `integration:register` or bootstrapping.
• Cause: Extra keys present in an integration’s config are passed to `updateOrCreate`, but the `integrations` table has no such column.
• Fix: Place driver-specific structures under `field_mapping` (or `driver_configuration`). For Magento 2, move `websites` to `integrations[*].field_mapping.websites`.

Webhooks

• Ensure `AKENEO_WEBHOOK_SECRET` is configured where applicable.
• Validate headers `X-Akeneo-Request-Signature` and `X-Akeneo-Request-Timestamp`.
• Use `task webhook:product:updated` to simulate an event (adjust method/URL per route).

Magento 2

• Verify `base_url` and tokens.
• Confirm endpoint casing: `rest/V1` (note capital `V`).
• Check network reachability from container to Magento 2.

Recovery

• Re-run imports: `php artisan akeneo:import:data {entity}`.

- For incremental syncs ensure `AKENEO_API_URL`, credentials and the per-entity `updated_at` settings exist.

- Use `--full` to bypass the updated filter while still advancing the sync watermark.

- If Akeneo client builder throws `Argument #1 ($baseUri) must be of type string, null given`, ensure `config('akeneo.base_uri')` is set (env `AKENEO_API_URL`) and clear config cache: `php artisan config:clear`.

• Retry failed jobs from Horizon UI.

External References

• Laravel Queues: https://laravel.com/docs/12.x/queues
• Laravel Horizon: https://laravel.com/docs/12.x/horizon
• Redis: https://redis.io/docs/
• MariaDB: https://mariadb.org/documentation/