Diagnosi errore 'Maximum execution time exceeded’

L’errore 'Maximum execution time of X seconds exceeded’ indica che uno script PHP ha superato il tempo massimo di esecuzione (max_execution_time). Su WordPress capita tipicamente durante backup, import/export, REST API pesanti o chiamate a servizi esterni lenti. Vediamo come diagnosticarlo con WP Error Monitor e risolverlo.

Come funziona max_execution_time

Il limite è impostato in php.ini, tipicamente 30 secondi. PHP-FPM può usare anche request_terminate_timeout. Esistono inoltre limiti lato webserver (nginx fastcgi_read_timeout, Apache Timeout). Se uno qualsiasi di questi viene superato, lo script viene interrotto. PHP genera Fatal error E_ERROR, mentre nginx mostra 504 Gateway Timeout.

Diagnosi con WP Error Monitor

L’agent intercetta il timeout via shutdown function. Nello stack trace estratto trovi l’ultima funzione in esecuzione, che è spesso il vero collo di bottiglia: una query SQL lenta, una HTTP request senza timeout, un wp_remote_get verso API offline, o un loop infinito. Abilita WPEM_TRACE_SLOW_QUERIES per loggare anche le query >500ms che potrebbero contribuire al timeout.

Quando NON aumentare il timeout

Aumentare max_execution_time è una toppa: nasconde il problema. Se l’operazione è legittimamente lunga (es. import 50k prodotti), va spostata in background con WP-Cron o Action Scheduler, dividendola in chunk piccoli. Se invece è un bug (loop infinito, query non indicizzata), va risolto a monte.

Action Scheduler in profondità

Action Scheduler è il framework usato da WooCommerce per job in background, ma può essere usato per qualsiasi task pesante. Caratteristiche chiave: 1) job persistenti in DB (non perduti su restart), 2) retry automatico in caso di fallimento, 3) batch processing con limit configurabile (default 25 job per esecuzione), 4) priorità per garantire job critici prima, 5) UI admin per ispezione/cancellazione. WP Error Monitor traccia anche i job Action Scheduler con tag 'context=action_scheduler' e segnala job stuck.

Setup nginx/Apache per long-running

Se proprio devi avere richieste lunghe via HTTP (es. API admin di import), configura: nginx fastcgi_read_timeout 300; client_max_body_size 100M; Apache Timeout 300, ProxyTimeout 300. Lato PHP: max_execution_time 0 (illimitato) SOLO per quel endpoint via set_time_limit(0) in alto allo script. Aggiungi rate limiting per evitare abuse: 1 richiesta/minuto per IP. Documenta che è un'endpoint speciale: rischio se cron lo chiama in loop.

Profilazione richieste lunghe con tideways

Per profilazione deep su richieste lunghe in produzione, Tideways è tool eccellente: profiling sampling-based con overhead <2%. Mostra call tree con tempo per funzione, identifica funzioni hot. Setup: estensione PHP tideways.so, daemon Tideways, dashboard SaaS o self-hosted. WP Error Monitor si integra: gli eventi 'execution_time_exceeded’ includono link al profile Tideways corrispondente (matching via timestamp+URL). Così' dal evento clicchi e vedi flame graph che mostra esattamente quale funzione ha consumato il tempo. Costo Tideways: piano starter 39 euro al mese.

Soft timeout vs hard timeout

Il timeout PHP hard kill il processo: nessuna pulizia, transaction DB inconsistente. Per operazioni dove la consistency conta (es. import ordini), usa soft timeout: set_time_limit() iniziale più alto (es. 300s), ma codice controlla tempo trascorso e si arresta graceful prima del limite (es. dopo 250s salva stato e ritorna). Action Scheduler implementa nativamente questo pattern: ogni job batch controlla microtime() e fa break se prossimo al limite. WP Error Monitor traccia entrambi: hard timeout come ERROR, soft timeout exit come INFO (controllo).

Quando rivolgersi a G Tech

Se il tuo team interno fatica a gestire timeout ricorrenti, identificare query lente o ottimizzare cron pesanti, il team G Tech offre consulenza dedicata: audit performance completo (analisi di 30 giorni di dati con report scritto e piano d’azione), affiancamento per implementare Action Scheduler o ottimizzazioni DB, formazione team interno (workshop di 8 ore in remote). Il costo di un'audit è tipicamente recuperato nel primo mese grazie alle ottimizzazioni applicate. Contattaci tramite il modulo dedicato per ricevere un preventivo personalizzato.

Procedura passo-passo

1. Filtra WP Error Monitor per 'message contains Maximum execution timè.
2. Apri l’evento e individua URL e action coinvolti.
3. Verifica se è un’operazione una tantum (import) o ricorrente (cron, AJAX).
4. Abilita WPEM_TRACE_SLOW_QUERIES nel sito e riproduci l’azione.
5. Identifica le query >500ms e ottimizzale (indici, paginazione, riduzione JOIN).
6. Sposta operazioni lunghe in coda async con Action Scheduler.
7. Se davvero necessario, alza max_execution_time SOLO per script CLI (set_time_limit(0) in script di import).
8. Migra le operazioni lunghe a Action Scheduler con as_schedule_single_action.
9. Configura webserver con timeout adeguati per endpoint specifici.

Errori comuni e come risolverli

• set_time_limit ignorato: safe_mode attivo o disable_functions blocca set_time_limit: configura il server.
• 504 Gateway Timeout ma nessun'errore PHP: Il timeout è lato webserver: alza fastcgi_read_timeout o proxy_read_timeout.
• Cron sempre in timeout: DISABLE_WP_CRON+system cron risolve di solito: il cron via HTTP eredita il timeout web.
• Action Scheduler job stuck: Lock corrotto o memoria esaurita: pulisci via wp action-scheduler clean.
• Endpoint long-running timeout webserver: Verifica TUTTI i livelli: PHP, nginx, eventuali load balancer.

Domande frequenti

D: Quale è un valore di max_execution_time sicuro?
R: 30s per web, 0 (illimitato) per CLI. Mai oltre 60s su frontend.

D: Posso vedere lo stack trace di un timeout?
R: Sì, WP Error Monitor cattura l’ultimo frame via shutdown handler.

D: Le richieste AJAX hanno lo stesso limite?
R: Sì, se passano da PHP-FPM. Usa REST API con autenticazione e job in background per operazioni pesanti.

D: Action Scheduler funziona senza WooCommerce?
R: Sì, è una libreria standalone installabile come plugin separato.

D: Posso vedere job pendenti?
R: Sì, wp-admin > Tools > Scheduled Actions o wp action-scheduler list.

Hai bisogno di aiuto?

Se vuoi affidare il monitoraggio WordPress al team di G Tech Group, scrivici tramite il modulo di contatto.