"Unable to Locate WordPress Content Directory (wp-content)": WordPress Is Looking Through FTP

"Unable to locate WordPress content directory (wp-content)." means WordPress is updating files through FTP or SSH, not directly, and could not find wp-content as that connection sees the filesystem. The folder exists. The FTP account's view of it does not match the server path WordPress is looking for. Either tell WordPress the FTP path with FTP_CONTENT_DIR, or fix file ownership so WordPress writes directly and never has to search.

Where WordPress raises it

The string is defined in WP_Upgrader as fs_no_content_dir and returned at several points of an update:

Outside updates, the same lookup appears in two places. Tools › Site Health has a critical test labelled "Unable to locate WordPress content directory" in its check of the upgrade-temp-backup folder. The scheduled cleanup of old backups writes the full sentence as a PHP notice, visible in the debug log when WP_DEBUG is on.

Why it can only happen over FTP or SSH

Every one of those checks calls $wp_filesystem->wp_content_dir(), which calls find_folder( WP_CONTENT_DIR ). What find_folder() does depends on the filesystem method:

• direct returns the path it was given, with a trailing slash. No lookup, no failure possible.
• ftpext, ftpsockets, ssh2 have to translate the server path, such as /home/acme/public_html/wp-content, into a path on the remote connection.

WordPress picks direct when it can create a test file and that file is owned by the same user as WordPress's own files. Otherwise it uses FTP or SSH and asks for credentials. FS_METHOD explains that choice in detail. So the first question is not "where is wp-content?" but "why is WordPress not writing directly?"

How the search works, and how it fails

For the FTP and SSH methods, find_folder() tries three things in order:

1. Constants (FTP methods only). If FTP_CONTENT_DIR is defined and the folder asked for is WP_CONTENT_DIR, that value is used as is.
2. The absolute path. If the server path exists on the connection too, it is used.
3. A search from the login directory. search_for_folder() lists the current directory, looks for each part of the server path in turn (home, acme, public_html, wp-content), follows any match, and as a last resort starts again from /.

The search usually works with an FTP account that is confined to its home folder. It fails in these situations:

• The account is limited to a subfolder. An FTP user created for one plugin or for an uploads folder cannot see wp-content at all.
• The server path goes through a symlink. If WP_CONTENT_DIR is /var/www/site/wp-content but /var/www/site links to /srv/clients/42/site, the FTP account sees only the real names, and the parts of the path never match.
• The listing is empty. WordPress puts FTP connections into passive mode, and directory listings travel over a separate data connection on a passive port. If a firewall blocks those ports, logging in succeeds and every listing comes back empty, so the search finds nothing.
• The account belongs to a different site. After a migration, saved FTP details can point to an account on another vhost.

The trap: a match in the wrong place

The last item has a worse variant than this error. When no part of the server path matches, the search falls back to any folder named wp-content in the directory it is looking at, starting with the login directory. If the server path is /var/www/live/wp-content and the FTP account's home is the root of a staging copy, the staging copy's wp-content qualifies. WordPress can quietly update the wrong copy, which shows up later as "the update succeeded but nothing changed", or as Destination folder already exists on a site you did not touch.

Defining the constants removes the guessing, and it is worth doing even when updates currently work.

Fix it

Preferred: make WordPress write directly. Give the WordPress files to the user PHP runs as. Once the test file and WordPress's files have the same owner, the method becomes direct, credentials stop being requested, and this error cannot occur. A shared group with group write permission is not enough on its own: the automatic choice compares owners, not groups, so that setup also needs FS_METHOD set to direct.

If you must use FTP: log in with the same FTP account in a client, note the paths it shows, and add them to wp-config.php:

define( 'FTP_BASE', '/public_html/' );
define( 'FTP_CONTENT_DIR', '/public_html/wp-content/' );
define( 'FTP_PLUGIN_DIR', '/public_html/wp-content/plugins/' );

These are FTP paths, as the client shows them after login, not server paths. WordPress adds a missing trailing slash itself. They apply only to the ftpext and ftpsockets methods.

If the method is ssh2: the FTP constants are ignored. Use an SSH account whose view of the filesystem includes the real WordPress path, or switch to direct writes.

If listings are empty: open the FTP server's passive port range in the firewall, or ask the host which range it uses.

Common mistakes

• Using server paths like /home/acme/public_html/wp-content/ in FTP_CONTENT_DIR on an account whose FTP root is /.
• Defining the constants and switching the method to SSH, then wondering why nothing changed.
• Leaving credentials for an old account in wp-config.php after a host change.
• Treating it as a permissions problem on wp-content itself and setting it to 777. The folder is not unwritable; it was not found. Folder creation errors look different, see could not create directory.

Verify

• An FTP client logged in as the same account opens the path in FTP_CONTENT_DIR and lists plugins and themes.
• A plugin update runs to the end; updating safely means trying a small plugin first.
• Tools › Site Health no longer lists "Unable to locate WordPress content directory".
• With direct writes, WordPress stops asking for FTP credentials altogether.