WordPress’s AI Client sends model requests through the same HTTP API as any other outbound call, which means a slow local model — one still loading weights, or generating tokens on a modest GPU — can hit a request timeout before it returns a single token. The direct fix is to raise the AI Client’s own default with the wp_ai_client_default_request_timeout filter, but that only works if the provider plugin, PHP, and your web server are also willing to wait. This guide walks through each layer in order, with the checks that tell you which one is actually cutting the connection.
It assumes WordPress 7.0 or later (the version that introduced the filter), a self-hosted model behind a provider plugin such as AI Provider for LM Studio or AI Provider for LiteLLM, and a reader comfortable adding a small mu-plugin.
Why local models time out when cloud models don’t
Hosted AI services keep models resident in memory and answer in well under a second of network time. A local setup behaves differently in two ways that matter for timeouts:
- Warm-up. The first request after the model server starts often pays the cost of loading weights into RAM or VRAM. The AI Provider for LM Studio plugin explicitly ships an “Extended HTTP timeout (180 s) to accommodate local model warm-up,” which is a useful indicator of how long that first call can take.
- Generation speed. Token throughput on consumer hardware is bounded by the GPU or CPU. A long completion can take minutes even after warm-up.
Neither problem is a bug, but both look like one when a request dies mid-generation.
The layers that can impose a deadline
Before changing anything, it helps to know how many clocks are running. A single “generate text” action passes through:
- The model server — its own inference time, plus any request timeout it enforces.
- The provider plugin — the connector that registers the provider with the WordPress AI Client. It may set an extended HTTP timeout of its own.
- The WordPress AI Client — the default request timeout, which is filterable.
- The WordPress HTTP API — the transport-level timeout passed to cURL or the PHP streams transport.
- PHP —
max_execution_time, and under PHP-FPM,request_terminate_timeout. - The web server or reverse proxy — nginx
fastcgi_read_timeoutandproxy_read_timeout, or Apache’sTimeOutandProxyTimeout.
Whichever clock expires first determines the error you see. Raising only the AI Client timeout while PHP still kills the script at 30 seconds produces a different failure, not a fix.
Step 1: Raise the AI Client default timeout
The WordPress developer reference documents apply_filters( 'wp_ai_client_default_request_timeout', float $default_timeout ) as a filter that “Filters the default request timeout in seconds for AI Client HTTP requests.” It was introduced in WordPress 7.0.0 and is used by WP_AI_Client_Prompt_Builder::__construct() in wp-includes/ai-client/class-wp-ai-client-prompt-builder.php.
Because the filter is applied in the prompt builder’s constructor, it runs each time a prompt builder is created. That makes it a per-request lever rather than a one-time boot setting.
Create a must-use plugin at wp-content/mu-plugins/ai-client-timeout.php:
<?php
/**
* Plugin Name: Raise AI Client request timeout
* Description: Gives slow local models more time to answer.
*/
add_filter(
'wp_ai_client_default_request_timeout',
function ( $default_timeout ) {
return 300.0;
}
);
Files in mu-plugins load automatically and cannot be deactivated from the admin, which is convenient for a site-wide setting and inconvenient if you get it wrong — keep the file small and version it.
Expected result: AI Client HTTP requests now default to 300 seconds instead of whatever the unfiltered value was. The documentation page does not publish that unfiltered default, so if you want a baseline, log the incoming value before overriding it:
add_filter(
'wp_ai_client_default_request_timeout',
function ( $default_timeout ) {
error_log( 'AI Client default timeout: ' . $default_timeout );
return 300.0;
}
);
Check the PHP error log after one generation to see the number that was in effect.
Step 2: Check the provider plugin’s own timeout
Provider plugins can extend the HTTP timeout independently. The AI Provider for LM Studio plugin, published by rtCamp, lists “Extended HTTP timeout (180 s) to accommodate local model warm-up” among its features. Its settings live under Settings > LM Studio Settings, and the plugin works without an API key in the default local setup. The plugin documentation describes the 180-second value as a built-in feature; it does not document a separate timeout field, so treat the core filter as your main control if you need longer.
If you route through a gateway instead, the AI Provider for LiteLLM plugin registers a litellm provider with the WordPress PHP AI Client SDK. It requires WordPress 7.0 and PHP 7.4, and its configuration is split across two screens: the API key on Settings > Connectors (or via the LITELLM_API_KEY environment variable or PHP constant), and the gateway base URL and default model on Settings > LiteLLM Provider (or via LITELLM_API_BASE).
A gateway adds a hop. If the LiteLLM process has its own request timeout, a slow backend model will be cut off there, and WordPress will report a connection failure no matter what the AI Client filter says. When a timeout only appears on the gateway path, check the gateway’s configuration first.
Step 3: Align PHP and web server limits
A 300-second AI Client timeout is meaningless if PHP terminates the request at 30 seconds. The relevant settings, in the order they usually bite:
- PHP
max_execution_time. Applies to scripts served through a web request. A PHP fatal error readingMaximum execution time of N seconds exceededin the error log confirms this is the layer that fired.set_time_limit()can extend it within a request where the host has not disabled it. - PHP-FPM
request_terminate_timeout. A pool-level limit that kills the worker regardless of what the script asks for. - nginx
fastcgi_read_timeoutandproxy_read_timeout. Defaults are often 60 seconds. A 504 Gateway Time-out in the browser usually points here. - Apache
TimeOutandProxyTimeout. The equivalent knobs on Apache and mod_proxy setups. default_socket_timeout. Relevant when the WordPress HTTP API falls back to the PHP streams transport rather than cURL.
Set the AI Client timeout to a value comfortably below your PHP and proxy ceilings, or raise those ceilings to match. A common arrangement is PHP and proxy limits at 300 seconds with the AI Client at 240, so the application fails with a clear error instead of the server killing the connection silently.
Per-request overrides for a specific endpoint
If you want to change the timeout only for calls to your model server, the WordPress HTTP API’s http_request_args filter lets you target a host. Scope it tightly, because it affects every outbound request that matches:
add_filter(
'http_request_args',
function ( $args, $url ) {
if ( false !== strpos( $url, 'localhost' ) ) {
$args['timeout'] = 300;
}
return $args;
},
10,
2
);
Replace the host fragment with your actual model endpoint. This is a blunt instrument: it will also stretch the timeout for any other request to that host, including health checks.
Verifying the change
- Confirm the mu-plugin loaded. A syntax error in an mu-plugin can take the site down, so check the front end loads before testing generation.
- Run a prompt you know takes longer than the old timeout — a long completion, or the first request after restarting the model server.
- Watch the model server’s own log. If the request never arrives, the problem is upstream of the model; if it arrives and inference finishes after WordPress has given up, the timeout is too low or the client is not waiting.
- Check the PHP error log for
Maximum execution time. That message means PHP, not the AI Client. - Check the web server error log for 504s. That means the proxy.
Matching symptoms to layers
| Symptom | Likely layer | First check |
|---|---|---|
| Request fails after a few seconds, before the model starts generating | AI Client default or HTTP transport timeout | Apply wp_ai_client_default_request_timeout, then retest |
| PHP fatal error naming an execution time | PHP max_execution_time or FPM request_terminate_timeout | PHP error log; set_time_limit() |
| Browser shows 504 Gateway Time-out | nginx or Apache proxy timeout | fastcgi_read_timeout, proxy_read_timeout, TimeOut |
| First request after a restart fails, the retry succeeds | Model warm-up | Preload the model, or raise the timeout for the first call |
| Fails only when routed through a gateway | Gateway request timeout | LiteLLM or proxy configuration |
These are diagnostic hypotheses, not conclusions. The log line or error page is what confirms the cause.
Tradeoffs and limits
Raising timeouts is a correctness fix, not a performance fix. Three consequences are worth planning for:
- PHP workers stay occupied. Every second a generation request waits is a second a PHP-FPM worker is unavailable. Several concurrent generations with a 300-second ceiling can exhaust a small pool and make the rest of the site slow or unresponsive.
- Browser and intermediary limits still apply. An admin AJAX request that runs for five minutes may be cut off by a browser, a CDN, or a corporate proxy that has no idea what WordPress is doing.
- Timeouts hide throughput problems. If a model takes four minutes to answer, a five-minute timeout makes the request succeed but does not make the workflow usable. Smaller quantizations, a shorter context, or a faster model often solve the real complaint.
Also note that the filter sets a default. Code that constructs its own request arguments can still pass a different timeout, so a plugin-level override can quietly win over your mu-plugin.
Next steps
Measure before you tune. Time a representative generation with the model already warm, add a margin for the first cold call, and set the AI Client timeout just above that number — then make sure PHP and the proxy sit above it. If you are still debugging, capture the exact error text, the model server’s log line, and the values of max_execution_time and your proxy timeout; those four data points usually identify the layer in one pass.
Readers running local models behind WordPress are welcome to share their environment — model, quantization, hardware, provider plugin, and the timeout values that worked — in the community so others can compare configurations.
FAQ
Does raising wp_ai_client_default_request_timeout fix every timeout?
No. It only changes the AI Client's default. If PHP's max_execution_time, PHP-FPM's request_terminate_timeout, or an nginx or Apache proxy timeout expires first, the request still fails — with a different error. Check the PHP and web server logs to see which limit fired.
What is the unfiltered default value of $default_timeout?
The WordPress developer reference documents the parameter as a float in seconds but does not publish the unfiltered default. Log the incoming value inside your filter callback to record the baseline for your installation.
Why does the first request fail and a retry succeed?
That pattern usually indicates model warm-up: the first call pays the cost of loading weights into memory. Options are to preload the model, raise the timeout for the first call, or accept a longer first response.
Where do I configure the LiteLLM provider in WordPress?
The API key goes on Settings > Connectors, or via the LITELLM_API_KEY environment variable or PHP constant. The gateway base URL and default model go on Settings > LiteLLM Provider, or via LITELLM_API_BASE.
Can I set the timeout for one request instead of the whole site?
The wp_ai_client_default_request_timeout filter runs when a prompt builder is constructed, so it can vary per request based on your own conditions. For HTTP-level control you can also use the http_request_args filter, scoped by URL, though that affects every matching outbound request.