I am trying to generate my API documentation using the darkaonline/l5-swagger package in my Laravel application. The application is running on Laravel Octane using RoadRunner as the server.
When I run the php artisan swagger:generate command, it seems to execute without error. However, when I try to access the documentation URL (/api/documentation), I get a 500 server error, and the following error appears in my RoadRunner logs:
[RR] 2026-02-11T19:26:00+00:00 ERR http error error="dial unix /var/run/php/php8.3-fpm.sock: connect: no such file or directory"
It seems like the package is trying to use FPM to generate something at runtime, but my environment is solely RoadRunner/Octane and doesn’t have an FPM socket.
Environment:
Laravel Version: 11, PHP 8.3
Package: darkaonline/l5-swagger v11
Package config: Default configuration published via php artisan vendor:publish --provider="DarkaOnline\L5Swagger\L5SwaggerServiceProvider"
I’ve verified that php artisan swagger:generate creates the public/docs folder and api-docs.json file. The JSON file looks valid.
I checked the l5-swagger.php config file, specifically the storage_path and swagger_json settings, which point to the correct file.
Question:
How can I configure l5-swagger or my Octane/RoadRunner setup to correctly serve the pre-generated OpenAPI documentation without trying to connect to a non-existent FPM socket at runtime? Is there a configuration I’m missing to ensure it uses the pre-built static file?
That error isn’t coming from l5-swagger itself. It’s coming from your HTTP stack.
dial unix /var/run/php/php8.3-fpm.sock means something is still trying to talk to PHP-FPM. With Octane + RoadRunner, FPM shouldn’t be involved at all. l5-swagger doesn’t use FPM to render the docs — it just serves a Blade view and loads the pre-generated JSON.
Since php artisan swagger:generate works and your public/docs/api-docs.json exists, generation is fine. The 500 is happening when the request hits /api/documentation, and RoadRunner (or your reverse proxy) is trying to hand that off to FPM.
Check your .rr.yaml and your web server config (Nginx, Caddy, etc.). If you see anything referencing fastcgi_pass or the FPM socket, that’s the problem. With Octane + RoadRunner, requests should be proxied directly to the RoadRunner port, not to FPM.
Also make sure in config/l5-swagger.php that generate_always is set to false, so it doesn’t attempt regeneration on every request. In production you should generate once during deploy and serve the static file.
In short: this isn’t a Swagger config issue. Something in your stack is still wired to FPM. Remove that, let RoadRunner handle all PHP execution, and /api/documentation should work normally.
Octane itself does not delegate anything to FPM. If you’re running octane:start –server=roadrunner, PHP is executed directly by RoadRunner. There’s no internal fallback to FPM inside Laravel or Octane.
If you’re still seeing dial unix /var/run/php/php8.3-fpm.sock, that means something in your stack is still trying to use FPM. Laravel won’t magically reference that socket on its own.
At that point I’d check three things:
First, make sure you’re actually hitting the Octane server. Temporarily stop Octane and hit the same URL. If you still get a response (or the same error), you’re not going through RoadRunner at all — your web server is routing somewhere else.
Second, double-check that you don’t have multiple server blocks in Nginx. It’s common to update one config file while another active vhost is still pointing to fastcgi_pass.
Third, confirm how RoadRunner is being started. If you’re using Docker or a process manager, make sure there isn’t an older PHP-FPM container still bound and referenced somewhere in the network config.
Bottom line: if that socket path appears in logs, it’s coming from your web server layer, not from Octane or l5-swagger. Laravel has no built-in behavior that would ever try to connect to /var/run/php/php8.3-fpm.sock.
That was it, I stopped Octane and realized the app was still responding, which immediately told me I wasn’t actually hitting RoadRunner. Turned out I had an old Nginx server block still configured with fastcgi_pass pointing to the FPM socket.
Once I removed that and properly proxied everything to the RoadRunner port, the 500 error disappeared and /api/documentation loaded normally. Swagger was fine the whole time — it was just my web server routing.
Appreciate the clarification about Octane not ever touching FPM. Thanks!
I removed all FPM references from Nginx and confirmed RoadRunner is running, but I’m still getting the same socket error. Could Octane itself be delegating something internally to FPM, or is there somewhere else Laravel might still be referencing it?