v1.13.0: config reload returns HTTP 500 "server is not registered, you must first call frankenphp.Init() with the WithServer() option" while workers boot (regression from v1.12.7) #2698

What happened?

Since v1.13.0, every config reload in worker mode makes FrankenPHP answer requests with an HTTP 500 and an empty body for as long as the new workers take to boot. The error log shows server is not registered, you must first call frankenphp.Init() with the WithServer() option (ErrNotRunning), raised at caddy.(*FrankenPHPModule).ServeHTTP (module.go:231). On v1.12.7, the same setup and load produce no 500s.

We found this with Laravel Octane: php artisan octane:reload does a GET /config/apps/frankenphp on the admin API and PATCHes the same body back with Cache-Control: must-revalidate. The bug also reproduces without Laravel and Octane, using a minimal worker script with a simulated bootstrap delay (see below).

Minimal reproduction

public/worker.php:

<?php
// BOOT_DELAY_MS simulates a framework bootstrap (Laravel takes ~300 ms here).
usleep((int) (getenv('BOOT_DELAY_MS') ?: 0) * 1000);

ignore_user_abort(true);
$handler = static function (): void {
    echo 'ok';
};
while (frankenphp_handle_request($handler)) {
    gc_collect_cycles();
}

Caddyfile:

{
	admin 127.0.0.1:{$ADMIN_PORT}
	auto_https disable_redirects

	frankenphp {
		worker {
			file /path/to/public/worker.php
			num 2
		}
	}
}

http://:{$PORT} {
	bind 127.0.0.1
	route {
		root * /path/to/public
		php_server {
			index worker.php
			try_files {path} worker.php
		}
	}
}

reload.sh (what Laravel Octane's octane:reload sends):

#!/bin/sh
ADMIN=${ADMIN:-http://127.0.0.1:8097}
curl -s "$ADMIN/config/apps/frankenphp" -o /tmp/fp-cfg.json
curl -s -X PATCH -H 'Content-Type: application/json' -H 'Cache-Control: must-revalidate' \
     --data-binary @/tmp/fp-cfg.json "$ADMIN/config/apps/frankenphp"

Steps:

1. PORT=3097 ADMIN_PORT=8097 BOOT_DELAY_MS=300 frankenphp run --config Caddyfile
2. Generate about 20 req/s against http://127.0.0.1:3097/ (we used batches of 4 parallel curl -m 10 every 200 ms).
3. Run reload.sh a few times, 10 s apart.
4. Count the non-200 responses.

Results (3 reloads per round, ~800–900 requests per round; v1.12.7 and v1.13.0 side by side on the same host):

• With a 0 ms boot the window is only ~28 ms, so you rarely hit it. It grows with worker boot time, which is why real applications hit it on every reload.
• The 500s start 0.05–0.5 s after the PATCH, and each one returns in under 1 ms (duration ≈ 0.0001 s) with Content-Length: 0 and only the Server: FrankenPHP Caddy header. So the request is rejected immediately, not queued.
• We saw 2 to 8 failed requests per reload at 20 req/s. That is every request arriving in that window.

Timeline of one reload (Laravel Octane setup, v1.13.0, debug log; timestamps are seconds after 1791409991):

.220  admin.api  received request  GET   /config/apps/frankenphp
.226  admin.api  received request  PATCH /config/apps/frankenphp   (Cache-Control: must-revalidate)
.227  admin      admin endpoint started
.254  frankenphp PHP init of the new config begins (first PHP warning logged)
.327  http.log.error  500 "server is not registered ..."   x4
.527  http.log.error  500 "server is not registered ..."   x4
.553  frankenphp FrankenPHP started 🐘 {"php_version":"8.4.26","total_threads":32,"worker_threads":2,"max_threads":32,"max_requests":0}
.553  frankenphp FrankenPHP stopped 🐘
.553  http       servers shutting down with eternal grace period
.747  first HTTP 200 again
.772  admin      stopped previous server

From the source, Server.ServeHTTP returns ErrNotRunning when isRegistered is false (server.go, around line 152), and FrankenPHPModule.ServeHTTP turns every non-ErrRejected error into a 500 (caddy/module.go:229-232). It looks like during a reload the old HTTP server keeps accepting requests while the FrankenPHP server it points at has already been unregistered and the new one is not registered yet. On v1.12.7 those requests were served (or waited) instead of failing.

This may be related to #2648 ("hand off PHP requests during configuration reloads", which mentions 503s), #2645 (the same class of problem on the SIGTERM shutdown path, which explicitly leaves the reload path unchanged) and #2469. As far as we can tell, the 500 ErrNotRunning variant on reload is not tracked yet.

A smaller side note: with the Laravel setup, both versions also occasionally leave a request hanging (no response within 10 s) during a reload: 1 in ~1,800 requests on v1.12.7 and 7 in ~1,800 on v1.13.0. The minimal reproduction did not show this, so we are not sure it is the same issue.

Build Type

deb packages

Worker Mode

Yes

Operating System

GNU/Linux

CPU Architecture

x86_64

PHP configuration

FrankenPHP v1.13.0 PHP 8.4 Caddy v2.11.7 h1:yj0Y4fYZGPkSvibBJ1sTWE33xC0fxztVyXEW5iIdUT4=   (go1.27.1)
  deb: frankenphp 1.13.0+php84-1, php-zts-embed 8.4.26-2, php-zts-cli 8.4.26-2 (pkg.henderkes.com, "Static-PHP:php-zts")
Compared with:
FrankenPHP v1.12.7 PHP 8.4 Caddy v2.11.4 h1:XKxkMTgNSizEvKG6QHue6cAsFOteU2qA61w2tKkCWi0=
  deb: frankenphp 1.12.7+php84-1, php-zts-embed 8.4.25-1

PHP 8.4.26, ZTS=1, ini: /etc/php-zts/php.ini (+ scan dir)
Extensions: Core date libxml openssl pcre zlib calendar ctype curl dom json fileinfo filter hash iconv SPL
mbstring pcntl session standard bz2 posix random readline Reflection exif SimpleXML sockets sodium tokenizer
xml xmlreader xmlwriter apcu bcmath brotli Phar ftp gd gettext gmp imagick intl ldap lz4 msgpack mysqlnd PDO
pgsql soap ssh2 tidy xsl yaml zip zstd igbinary memcached mysqli pdo_mysql pdo_pgsql redis Zend OPcache
(extension packages are still at 8.4.25 in the repository; the minimal worker uses none of them)

OS: Debian 12.15 (bookworm), kernel 6.1.0-53-amd64, 16 vCPU
Laravel setup: Laravel Framework 12.61.1, laravel/octane v2.17.4,
  `php artisan octane:start --server=frankenphp --workers=2 --max-requests=500`

Relevant log output

{"level":"error","ts":1791410386.07222,"logger":"http.log.error","msg":"server is not registered, you must first call frankenphp.Init() with the WithServer() option","request":{"remote_ip":"127.0.0.1","remote_port":"45880","client_ip":"127.0.0.1","proto":"HTTP/1.1","method":"GET","host":"127.0.0.1:3097","uri":"/","headers":{"User-Agent":["curl/7.88.1"],"Accept":["*/*"]}},"duration":0.000226745,"status":500,"err_id":"pp5za8t9u","err_trace":"caddy.(*FrankenPHPModule).ServeHTTP (module.go:231)"}

# HTTP response for such a request:
HTTP/1.1 500 Internal Server Error
Server: FrankenPHP Caddy
Content-Length: 0