Worker Operations and Troubleshooting

Which Worker Is Used

When Enable External Worker = No, or External Worker URL is empty, enabled PHP handles requests. With the external worker enabled and a URL configured, Node/Cloudflare takes priority. If it is unavailable or cannot start the request, enabled PHP is the backup. Enable PHP Worker = No means external failures are reported without PHP backup. Test Connection checks both configured external and enabled PHP workers independently.

Health results are cached for 30 seconds. A recovered external worker takes priority again after that cache expires; Test Connection clears it. Provider credential, model and quota errors do not switch runtimes. Work already accepted by a worker uses durable recovery where available, rather than a second provider call.

Timeouts and Capacity

Control	Default	Scope
AI Request Timeout	25 seconds; zero uses 25	Direct PHP and synchronous worker bridge, further bounded by the remaining PHP request budget.
Max Concurrent AI Requests	2; zero disables this limit	Magento's guarded synchronous requests.
Idle Timeout	60 seconds	Worker provider stream with no received data.
Max Request Duration	300 seconds; maximum 600	Absolute worker generation limit, even while data arrives.
`MAX_CONCURRENT_REQUESTS`	8	Node runtime active requests plus background work, counted conservatively.
Max Concurrent Deliveries	1 per provider	Background scheduler's simultaneous deliveries.
Bulk Max Attempts	3	Scheduled bulk attempts, subject to job state and expiry.
`SHUTDOWN_GRACE_MS`	30000	Node shutdown wait for in-flight requests/background work.

These controls do not rewrite PHP, Nginx or Redis configuration. Increasing output tokens does not increase a request deadline. A custom proxy can still close a connection earlier than the application limit.

Cron and Background Jobs

Keep Magento cron running for scheduler reconciliation, recovery and cleanup. Submission can start the first chunk immediately; later progress still needs cron. Cloudflare additionally requires the hyvaAiWorkerJobChunk consumer; self-hosted automatic dispatch does not.

bin/magento hyva:ai-worker:scheduler:run --status
bin/magento hyva:ai-worker:scheduler:run --dry-run

Status reports transport, scheduler health and unclaimed work. Dry-run reports intended actions without dispatching. In development, --watch runs reconciliation until work is idle; it is not a substitute for production cron.

The scheduler uses persisted delivery/job state to dispatch, recover and retry. A delivery records one provider call, including its outcome and usage. Retries may create additional provider calls and charges. Restart consumers after deployment so they know new feature handlers.

Staging with HTTP Basic Authentication

For Basic-auth staging, configure the following on the worker:

Worker setting	Storage	Example
`MAGENTO_HTTP_AUTH_ORIGIN`	Variable	`https://staging.example.com`
`MAGENTO_HTTP_AUTH_USERNAME`	Secret	Staging login username.
`MAGENTO_HTTP_AUTH_PASSWORD`	Secret	Staging login password.

Set all three or leave all three unset. The origin must exactly match Magento's request/callback HTTPS origin, including any port and excluding any path. If using Worker Callback Base URL, use its origin. For Node/Cloudflare, configure MAGENTO_ALLOWED_ORIGIN consistently. Bundled PHP uses the configured callback origin automatically.

The worker sends Basic credentials in Authorization and its one-time Magento credential in X-Hyva-Ai-Worker-Token. Forward the latter header through the proxy to PHP. The credentials are restricted to the configured origin, never sent to provider APIs, and redirects are refused.

The two route families must reach the normal Magento front controller:

/hyva_ai_worker/request/consume/id/<request-id>
/hyva_ai_worker/job/callback/id/<job-id>/delivery/<delivery-id>

This supports HTTP Basic auth, not an interactive SSO form or WAF challenge. A dedicated callback hostname or narrow authentication exception remains an alternative when your infrastructure requires it. Retain Magento's endpoint authentication.

Save/deploy both sides and run Test Connection. For Node/Docker, update the external environment and restart; for Cloudflare, deploy the variables and secrets. For bundled PHP, expose the three variables to PHP-FPM and reload it through your normal deployment. Initial access to a Basic-auth-protected PHP worker route also needs the appropriate browser/Magento credentials.

Deployment and Secret Rotation

Deploy matching Magento and runtime versions, refresh configuration/DI/admin assets and restart long-running consumers. For Node/Docker, update the adapter as well as worker.js; runtime safeguards do not appear by updating only the relay script.

Keep secrets across ordinary updates.

Rotating the signing secret breaks in-flight work

Rotating the signing secret invalidates outstanding tokens. Coordinate both Magento and the worker and expect in-flight work to fail. Environment-provided secrets take precedence over stored Magento fields, so editing the admin field alone may not change the effective value.

Troubleshooting

Symptom	What to check
No provider group or models	Confirm that provider's package is installed/enabled and DI/configuration is refreshed. Provider settings come from their individual packages.
Model listed, but request rejected	Check provider account access, model retirement and the feature/transport capability. Saved compatibility choices are not live availability checks.
Saved DeepL key cannot be decrypted	Re-enter the correct Free/Pro key and save on this installation, then run the provider's usage test. Do not paste an encrypted value from another installation.
Provider test passes, generation fails	Worker connection, callback delivery and feature settings are separate. Test the actual generation route and image model where relevant.
Worker test fails or returns HTML/401	Check URL, matching secrets, version, Basic auth/WAF challenges and header forwarding. Save configuration before testing.
HTTP 410 / `request_unavailable`	One-time request may be expired, already consumed, missing or rejected during retrieval. Inspect worker and Magento errors plus routing/auth headers. During fallback, this may mean the external worker already accepted the job. Let result recovery finish before starting another generation; reusing a consumed token cannot call the provider again.
`ECONNREFUSED`, DNS or certificate error	Check from PHP and the worker, not only the browser. Container loopback/DNS and missing CA trust are common causes.
`No worker is ready`, PHP line shows a refused connection	PHP cannot open the store's own URL from inside its container. The store host must resolve to the web proxy, and a hosts entry written when the container was created goes stale once the proxy restarts on another address. Check with `curl` from inside the PHP container and recreate it. With Warden: `warden env up`, then `warden env restart varnish` if Varnish answers 503 afterwards.
PHP worker returns 404	Check Enable PHP Worker and normal module deployment. PHP works with Enable External Worker set to No; enabling the external worker leaves PHP available as a backup.
PHP worker hangs during retrieval/callback	Check spare PHP-FPM capacity, self-reachable Magento URLs and TLS trust. Single-process PHP servers cannot serve nested requests.
Stream appears only at the end	Check buffering/caching in the worker's proxy or load balancer.
HTTP 503 with Retry-After	Node may be at its concurrency limit, or an upstream provider may be unavailable. Identify which endpoint returned it before changing capacity.
Budget exhausted or truncated output	Reduce request size, use an appropriate model/output limit or a durable worker flow. Do not raise every Magento server timeout to accommodate long AI work.
Content/images unavailable with PHP default	Set the relevant Generation/Image Generation override to AI Worker and configure its model.
Interactive generation works, bulk remains queued	Check cron, detected transport, Cloudflare consumer and whether consumers were restarted after deployment.
`handler_unavailable`	A running consumer may have old DI configuration; restart it after deploying the feature module.
Preview/apply fails on a new page	Complete initial creation and save, then reopen the entity before generating. Confirm a valid entity ID and normal preview/style compilation.
Job result invalid or incomplete	Review the feature's validation message. CMS retains the previous valid candidate; do not bypass validation to apply partial output.

Inspect Magento logs and worker runtime/platform logs around the same request. Avoid recording signed tokens, plaintext secrets or complete private prompts in shared diagnostics. A worker connectivity test is not evidence that a provider request, callback and draft save all completed.