{"id":101,"date":"2026-07-18T00:00:00","date_gmt":"2026-07-18T00:00:00","guid":{"rendered":"http:\/\/\/var\/www\/html\/?p=101"},"modified":"2026-07-19T16:42:01","modified_gmt":"2026-07-19T16:42:01","slug":"php-fpm-socket-permission-denied-nginx-user-group-mismatch-on-ubuntu-2204-lts","status":"publish","type":"post","link":"https:\/\/staging.butitworkedlocal.com\/?p=101","title":{"rendered":"Fixing PHP-FPM Socket Permission Denied: Nginx User\/Group Mismatch on Ubuntu 22.04 LTS"},"content":{"rendered":"\n

Resolve Nginx 502 Bad Gateway errors caused by PHP-FPM Unix socket permission issues on Ubuntu 22.04 LTS by correcting user, group, and listen mode configurations.<\/strong><\/p>\n\n\n

When deploying or managing web applications on an Ubuntu 22.04 LTS server, it's common to encounter the dreaded "502 Bad Gateway" error. Often, this indicates a communication breakdown between Nginx, your web server, and PHP-FPM, the FastCGI Process Manager that executes your PHP code. A frequent culprit is a permission denied<\/code> error when Nginx attempts to connect to the PHP-FPM Unix socket, typically stemming from a mismatch in user and group permissions.<\/p>\n\n

This guide will walk you through diagnosing and resolving this issue by ensuring Nginx has the necessary access to the PHP-FPM socket, restoring your web application's functionality.<\/p>\n\n

Symptom & Error Signature<\/h3>\n\n

Users attempting to access your website will typically see a "502 Bad Gateway" error page directly from Nginx. On the backend, your Nginx error logs will clearly indicate the permission issue.<\/p>\n\n

Browser Output:<\/strong>\n<\/code>`\n502 Bad Gateway\nnginx\/1.22.1\n<\/code>`<\/p>\n\n

Nginx Error Log (\/var\/log\/nginx\/error.log<\/code> or similar):<\/strong>\n<\/code>`nginx\n2023\/10\/27 10:35:45 [crit] 12345#12345: *1 connect() to unix:\/var\/run\/php\/php8.1-fpm.sock failed (13: Permission denied) while connecting to upstream, client: 192.168.1.100, server: example.com, request: "GET \/index.php HTTP\/1.1", upstream: "fastcgi:\/\/unix:\/var\/run\/php\/php8.1-fpm.sock:", host: "example.com"\n<\/code>`<\/p>\n\n

The key part of this error is (13: Permission denied) while connecting to upstream<\/code>. This specifically tells us that Nginx could not establish a connection to the PHP-FPM Unix socket due to insufficient permissions.<\/p>\n\n

Root Cause Analysis<\/h3>\n\n

The "PHP-FPM socket permission denied" error arises from a security mechanism designed to prevent unauthorized processes from interacting with the PHP-FPM service. When Nginx tries to communicate with PHP-FPM via a Unix domain socket, it requires read\/write access to that socket file.<\/p>\n\n

Here's a breakdown of the common underlying reasons:<\/p>\n\n

  1. Nginx User\/Group Mismatch:<\/strong><\/li>
  2. * By default, Nginx on Ubuntu runs as the www-data<\/code> user and group.<\/li>
  3. * PHP-FPM also typically runs its pools as www-data<\/code>. However, if the PHP-FPM pool is configured to run under a different user or group (e.g., php-fpm<\/code>, a custom application user, or the root<\/code> user by mistake), the socket it creates might not be accessible to www-data<\/code>.<\/li><\/ol>\n\n
    1. Incorrect PHP-FPM Pool Socket Configuration (listen.owner<\/code>, listen.group<\/code>, listen.mode<\/code>):<\/strong><\/li>
    2. * The PHP-FPM pool configuration (e.g., \/etc\/php\/8.1\/fpm\/pool.d\/www.conf<\/code>) defines how the Unix socket is created.<\/li>
    3. * If listen.owner<\/code> or listen.group<\/code> are set to users\/groups other than www-data<\/code>, and listen.mode<\/code> is restrictive (e.g., 0600<\/code>), Nginx (running as www-data<\/code>) will be denied access.<\/li>
    4. * The listen.mode<\/code> directive determines the file permissions for the socket. A common secure setting is 0660<\/code>, which grants read\/write to the owner and group, but denies others. If the Nginx user is not part of the socket's group, this will fail.<\/li><\/ol>\n\n
      1. Parent Directory Permissions:<\/strong><\/li>
      2. * Even if the socket file itself has correct permissions, the directory containing it (e.g., \/var\/run\/php\/<\/code>) must have appropriate permissions for the Nginx user to traverse and access the socket within. Incorrect directory permissions (e.g., 0700<\/code> owned by root<\/code>) can prevent Nginx from even seeing the socket file.<\/li><\/ol>\n\n
        1. SELinux or AppArmor Interference (Less Common on Ubuntu):<\/strong><\/li>
        2. * While less frequent for this specific error on a default Ubuntu setup, security modules like SELinux (on Red Hat-based systems) or AppArmor (on Ubuntu) can enforce additional access controls that might block Nginx from connecting to the socket. This usually manifests with explicit denials in audit logs.<\/li><\/ol>\n\n

          Step-by-Step Resolution<\/h3>\n\n

          Follow these steps to diagnose and correct the PHP-FPM socket permission issue. We'll assume PHP 8.1 for the examples, adjust versions as needed (e.g., php8.2-fpm<\/code>).<\/p>\n\n

          1. Verify Nginx User and PHP-FPM Socket Path<\/h4>\n\n

          First, confirm the user Nginx is running as and the exact socket path Nginx is configured to use.<\/p>\n\n

          1. Check Nginx User:<\/strong><\/li>
          2. Typically, Nginx runs as www-data<\/code>. You can verify this in your main Nginx configuration (\/etc\/nginx\/nginx.conf<\/code>) or by inspecting running processes.<\/li><\/ol>\n\n
                grep "user" \/etc\/nginx\/nginx.conf\n    ```\n    Expected output:\n    ```\n    user www-data;\n    ```\n    If not explicitly set, Nginx defaults to the user it was started by (often `root`, then it drops privileges to `www-data`).\n    You can also check process ownership:\n    ```bash\n    ps aux | grep nginx | grep -v grep\n    ```<\/code><\/pre>\n\n
            1.  Confirm PHP-FPM Socket Path in Nginx Configuration:<\/strong><\/li>
            2.     Navigate to your Nginx site configuration (e.g., \/etc\/nginx\/sites-available\/example.com.conf<\/code>) and locate the fastcgi_pass<\/code> directive.<\/li><\/ol>\n\n
                  grep -r "fastcgi_pass" \/etc\/nginx\/sites-enabled\/\n    ```\n    Example output from a config file:\n    ```nginx\n    # \/etc\/nginx\/sites-available\/example.com.conf\n    location ~ .php$ {\n        include snippets\/fastcgi-php.conf;\n        fastcgi_pass unix:\/var\/run\/php\/php8.1-fpm.sock;\n    }\n    ```<\/code><\/pre>\n\n
              2. Inspect PHP-FPM Pool Configuration<\/h4>\n\n
              The most common cause is incorrect settings in the PHP-FPM pool configuration. We'll edit the www.conf<\/code> file, which manages the default PHP-FPM pool.<\/p>\n\n
              1.  Open the PHP-FPM Pool Configuration:<\/strong><\/li>
              2.     <\/code>`bash<\/li>
              3.     sudo nano \/etc\/php\/8.1\/fpm\/pool.d\/www.conf<\/li>
              4.     <\/code>`<\/li><\/ol>\n\n
                1.  Verify user<\/code> and group<\/code> Directives:<\/strong><\/li>
                2.     Ensure the user<\/code> and group<\/code> directives match the Nginx user (www-data<\/code>).<\/li><\/ol>\n\n
                      ; Unix user\/group of processes\n    ; Note: The user and group specified here are used for all processes of this pool.\n    ;       This also affects the ownership of the socket if listen.owner\/listen.group\n    ;       are not set, or set to '0'.\n    user = www-data\n    group = www-data<\/code><\/pre>\n\n
                  1.  Verify listen<\/code> Directives (Crucial):<\/strong><\/li>
                  2.     These directives control the ownership and permissions of the Unix socket file itself.<\/li><\/ol>\n\n
                        ; The address on which to accept FastCGI requests.\n    ; Valid syntaxes are:\n    ;   'ip.add.re.ss:port'    - to listen on a TCP socket to a specific address on a specific port;\n    ;   'port'                 - to listen on a TCP socket to all addresses on a specific port;\n    ;   '\/path\/to\/unix\/socket' - to listen on a Unix socket.\n    ; Note: This value is in effect only when the listening domain is a Unix socket.\n    ;       The file created is owned by the user\/group specified in 'listen.owner' and 'listen.group'.<\/code><\/pre>\n\n
                    ; Set permissions for unix socket, if one is used. In general to make it work\n    ; with Nginx you will want to set it to 0660 or 0666.\n    ; listen.owner = www-data\n    ; listen.group = www-data\n    ; listen.mode = 0660\n    <\/code>`<\/p>\n\n
                    Ensure these lines are uncommented<\/strong> (no leading semicolon ;<\/code>) and configured as follows:<\/p>\n\n
                        listen.owner = www-data\n    listen.group = www-data\n    listen.mode = 0660<\/code><\/pre>\n\n
                    •   listen.owner = www-data<\/code>: Sets the owner of the socket file to www-data<\/code>.<\/li>
                    •   *   listen.group = www-data<\/code>: Sets the group of the socket file to www-data<\/code>.<\/li>
                    •   *   listen.mode = 0660<\/code>: Sets the file permissions to rw-rw----<\/code>. This means the owner (www-data<\/code>) and the group (www-data<\/code>) have read and write access, while others have no access. Since Nginx runs as www-data<\/code>, it will have full access.<\/li><\/ul>\n\n
                      [!WARNING]\n    > Do not set listen.mode = 0777<\/code> or similarly permissive modes unless absolutely necessary and you understand the security implications. 0660<\/code> with correct owner\/group is typically secure and sufficient.<\/p><\/blockquote>\n\n
                      1.  Save and Exit:<\/strong><\/li>
                      2.     Save the changes (Ctrl+O<\/code>, then Enter<\/code>) and exit nano<\/code> (Ctrl+X<\/code>).<\/li><\/ol>\n\n
                        3. Restart PHP-FPM and Nginx<\/h4>\n\n
                        After modifying the PHP-FPM configuration, you must<\/em> restart the PHP-FPM service for changes to take effect. It's also good practice to restart Nginx.<\/p>\n\n
                        sudo systemctl restart php8.1-fpm\nsudo systemctl restart nginx<\/code><\/pre>\n\n
                        [!IMPORTANT]\nIf systemctl restart php8.1-fpm<\/code> fails, check the PHP-FPM logs for syntax errors:\nsudo journalctl -u php8.1-fpm -f<\/code><\/p><\/blockquote>\n\n
                        4. Verify Socket File Permissions<\/h4>\n\n
                        After restarting PHP-FPM, the socket file should be recreated with the new permissions. Verify its ownership and mode.<\/p>\n\n
                        ls -l \/var\/run\/php\/php8.1-fpm.sock<\/code><\/pre>\n\n
                        Expected output (or similar, depending on PHP version):\n<\/code>`\nsrw-rw—- 1 www-data www-data 0 Oct 27 10:45 \/var\/run\/php\/php8.1-fpm.sock\n<\/code>`\nThe s<\/code> at the beginning indicates it's a socket file. Crucially, the owner and group should both be www-data<\/code>, and the permissions should be rw-rw----<\/code>.<\/p>\n\n
                        If the group is something other than www-data<\/code> (e.g., php-fpm<\/code>), you have two main options:\n1.  Change listen.group<\/code> in www.conf<\/code> to www-data<\/code><\/strong> (as done in Step 2, and recommended).\n2.  Add the www-data<\/code> user to that specific group.<\/strong> For example, if the socket's group is php-fpm<\/code>:\n    <\/code>`bash\n    sudo usermod -aG php-fpm www-data\n    sudo systemctl restart nginx\n    <\/code>`\n    Then, ensure listen.mode = 0660<\/code> is set in www.conf<\/code> and restart php8.1-fpm<\/code>.<\/p>\n\n
                        5. Check Parent Directory Permissions<\/h4>\n\n
                        While less common to be the primary cause for this specific error<\/em> after correcting FPM config, incorrect directory permissions for \/var\/run\/php\/<\/code> can also contribute. Ensure the Nginx user can traverse this directory.<\/p>\n\n
                        ls -ld \/var\/run\/php<\/code><\/pre>\n\n
                        Expected output:\n<\/code>`\ndrwxr-xr-x 2 root root 60 Oct 27 10:45 \/var\/run\/php\n<\/code>`\nThe drwxr-xr-x<\/code> (755<\/code>) permissions allow root<\/code> full access, and all other users (including www-data<\/code>) read and execute (traverse) access. This is generally sufficient. If the permissions are more restrictive (e.g., drwx------<\/code>), you might need to adjust them:<\/p>\n\n
                        sudo chmod 755 \/var\/run\/php\n```<\/code><\/pre>\n\n
                        6. Test Your Website<\/h4>\n\n
                        After completing the steps and restarting services, try accessing your website again. The "502 Bad Gateway" error should now be resolved, and your PHP application should load correctly.<\/p>\n\n
                        If the issue persists, review the Nginx and PHP-FPM error logs again (e.g., sudo tail -f \/var\/log\/nginx\/error.log<\/code> and sudo journalctl -u php8.1-fpm -f<\/code>) for any new errors or clues. There might be a different underlying problem, or a subtle configuration mistake.<\/p>","protected":false},"excerpt":{"rendered":"
                        Resolve Nginx 502 Bad Gateway errors caused by PHP-FPM Unix socket permission issues on Ubuntu 22.04 LTS by correcting user, group, and listen mode configurations.<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[63],"tags":[271,55,11,220,111,222],"class_list":["post-101","post","type-post","status-publish","format-standard","hentry","category-runtimes","tag-502-bad-gateway","tag-nginx","tag-permissions","tag-php-fpm","tag-ubuntu-22-04","tag-unix-socket"],"_links":{"self":[{"href":"https:\/\/staging.butitworkedlocal.com\/index.php?rest_route=\/wp\/v2\/posts\/101","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/staging.butitworkedlocal.com\/index.php?rest_route=\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/staging.butitworkedlocal.com\/index.php?rest_route=\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/staging.butitworkedlocal.com\/index.php?rest_route=\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/staging.butitworkedlocal.com\/index.php?rest_route=%2Fwp%2Fv2%2Fcomments&post=101"}],"version-history":[{"count":1,"href":"https:\/\/staging.butitworkedlocal.com\/index.php?rest_route=\/wp\/v2\/posts\/101\/revisions"}],"predecessor-version":[{"id":220,"href":"https:\/\/staging.butitworkedlocal.com\/index.php?rest_route=\/wp\/v2\/posts\/101\/revisions\/220"}],"wp:attachment":[{"href":"https:\/\/staging.butitworkedlocal.com\/index.php?rest_route=%2Fwp%2Fv2%2Fmedia&parent=101"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/staging.butitworkedlocal.com\/index.php?rest_route=%2Fwp%2Fv2%2Fcategories&post=101"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/staging.butitworkedlocal.com\/index.php?rest_route=%2Fwp%2Fv2%2Ftags&post=101"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}