Create a folder if it doesn't already exist

Create a folder if it doesn't already exist

  1. Blog
  2. 15 November 2026
  3. 3 min read

Stefan Bogdanescu

Founder & Senior Architect

Create a Folder if It Doesn't Already Exist

When deploying WordPress sites on certain shared hosting environments, you may encounter a situation where the core installation script successfully sets up the database and theme files but leaves the wp-content/uploads directory missing. This specific issue has been observed with Bluehost's cPanel installer, which differs from competitors like HostGator in how it handles post-installation directory creation. If this folder is absent, any attempt to upload media will fail immediately, resulting in a 500 Internal Server Error or a persistent "Unable to write file" message in the admin interface.

While manual intervention—such as logging into the cPanel File Manager and creating the uploads directory yourself—is technically possible, it creates a friction point for users who might have forgotten to do so before uploading their first image. A more robust solution involves ensuring the directory exists programmatically within your theme's initialization logic. This approach guarantees that the site remains functional regardless of whether the hosting provider created the folder automatically or if the user missed a step during manual setup.

The most reliable way to handle this in a WordPress theme is by leveraging the wp_register_upload_dir hook or, more commonly in modern themes, by adding a check within your theme's main asset loading file. You can place logic in your functions.php file to verify the path and create it if necessary. Here is a standard implementation that checks for the existence of the directory before attempting to write to it:

function ensure_uploads_directory_exists() {
    $upload_path = wp_upload_dir();
    
    // Check if the 'basedir' exists
    if (!file_exists($upload_path['basedir'])) {
        // Attempt to create the directory
        mkdir($upload_path['basedir'], 0755, true);
        
        // Verify success
        if ($upload_path['error']) {
            wp_die(esc_html__('Unable to create uploads folder. Please contact your host.', 'your-textdomain'));
        }
    }
}

add_action('after_setup_theme', 'ensure_uploads_directory_exists');

This snippet utilizes wp_upload_dir(), which returns the path to the upload directory and various subdirectories needed for media management. The function checks if the base directory exists using file_exists(). If it does not, mkdir() is called with the third argument set to true, enabling recursive creation of parent directories if they are missing. This is crucial because sometimes the entire wp-content folder hierarchy might be incomplete on a fresh install.

There are important trade-offs to consider when implementing this code. The primary concern is security and file permissions. While creating a directory with standard permissions like 0755 is safe for web servers, you must ensure that the parent directories (wp-content, wp-includes) already have the correct ownership and permissions set. If the server cannot write to the parent folder due to restrictive cPanel settings, the recursive creation will fail even if the code logic is correct.

Additionally, this approach should generally be placed in a child theme or a custom plugin rather than the main theme's functions.php. Hardcoding file system checks into a core theme can lead to conflicts if the theme is updated or switched out later. The logic remains valid, but encapsulating it ensures longevity across different hosting environments and theme versions.

If you are working with a headless setup or integrating WordPress as an API backend without a traditional admin area, this check becomes even more critical. Without a human operator to manually create folders in cPanel, the application must self-heal these structural gaps immediately upon bootstrapping. This ensures that the first request to upload an image does not result in a confusing server error, maintaining a seamless user experience regardless of the hosting provider's default configuration.

Our network