Image upload failures

When creating notes or adding comment attachments in Annotatr, images are uploaded to your WordPress media library. If uploads fail, display error messages, or result in blank images, the issue typically relates to server configuration, file size limits, or permissions.

This guide will help you identify and resolve common image upload problems, ensuring screenshots and attachments save correctly every time.

Minimum server requirements for uploads

Annotatr processes and optimises images during upload. Ensure your server meets these minimum requirements:

Critical PHP settings:

• upload_max_filesize: 10MB minimum (recommended: 25MB)
• post_max_size: 12MB minimum (recommended: 30MB)
• memory_limit: 256MB minimum (recommended: 512MB)
• max_execution_time: 30 seconds minimum (recommended: 60s)
• max_input_time: 60 seconds minimum

Checking your current settings:

1. Go to Tools → Site Health → Info in WordPress
2. Click the Server section
3. Review the values listed above
4. If any are below minimum recommendations, increase them

How to increase PHP limits

Method 1: Edit php.ini (recommended)

If you have access to your server’s php.ini file:

1. Locate your php.ini file (usually in /etc/php/7.4/ or similar)
2. Add or modify these lines:upload_max_filesize = 25M post_max_size = 30M memory_limit = 512M max_execution_time = 60 max_input_time = 60
3. Save the file
4. Restart your web server (Apache or Nginx)
5. Verify changes in Site Health

Method 2: Edit wp-config.php

Add this line above “/* That’s all, stop editing! */”:

define('WP_MEMORY_LIMIT', '512M');

Note: This only affects memory_limit, not upload sizes.

Method 3: Contact your hosting provider

If you can’t access server files:

• Contact your hosting support
• Request the above PHP settings be increased
• Most hosts can make these changes quickly
• Some hosts offer settings panels (cPanel, Plesk) to adjust values

Common error messages and solutions

“The uploaded file exceeds the upload_max_filesize directive”

Cause: File is larger than your server’s upload_max_filesize setting.

Solution: Increase upload_max_filesize to at least 25MB using methods above.

“The uploaded file exceeds the post_max_size directive”

Cause: Total POST data (including file) exceeds post_max_size.

Solution: Increase post_max_size to at least 30MB (should be larger than upload_max_filesize).

“Fatal error: Allowed memory size exhausted”

Cause: PHP ran out of memory whilst processing the image.

Solution: Increase memory_limit to 512MB or higher.

“Unable to create directory” or “Failed to write file to disk”

Cause: WordPress can’t write to the uploads directory.

Solution: Fix file permissions (see below).

“This file type is not allowed for security reasons”

Cause: Annotatr rejects certain file types (SVG files are blocked for XSS protection).

Solution: Use PNG, JPG, JPEG, GIF, or WebP formats only.

Screenshot: An error message popup in Annotatr showing “Upload failed: The uploaded file exceeds the upload_max_filesize directive” with a red X icon.

File permissions issues

WordPress needs write access to the uploads directory:

Checking permissions:

1. Connect to your server via FTP or SSH
2. Navigate to wp-content/uploads/
3. Check folder permissions (should be 755 or 775)
4. Check subdirectory permissions (year/month folders)

Fixing permissions (via SSH):

cd /path/to/wordpress/wp-content/
chmod 755 uploads
chmod 755 uploads/*
chmod 644 uploads/*/*

Fixing permissions (via FTP):

1. Right-click the uploads folder
2. Select “File Permissions” or “Change Permissions”
3. Set to 755 (or 775 if 755 doesn’t work)
4. Check “Apply to subdirectories”
5. Save changes

Image size and optimisation

Annotatr automatically optimises uploaded images, but you can help prevent issues:

Automatic optimisations:

• Images resized to maximum 1800px width (maintains aspect ratio)
• WebP format used for modern browsers (80% quality)
• JPEG format for opaque images (85% quality)
• PNG for images with transparency (compression level 6)
• Maximum file size enforced: 5MB post-optimisation

If very large images fail:

• Use the “Select area” feature instead of full-page screenshots
• Reduce browser zoom level before capturing
• Close unnecessary browser tabs (frees memory)
• Capture specific elements rather than entire layouts

Disk space issues

Running out of server disk space will cause uploads to fail:

Checking disk space:

1. SSH into your server and run df -h
2. Or check your hosting control panel’s disk usage section
3. Ensure at least 1-2GB free space available

Freeing up space:

• Delete old WordPress backups
• Clear cache plugin storage
• Remove unused media files
• Delete old log files
• Upgrade hosting plan if consistently running low

Image processing library issues

WordPress uses GD Library or ImageMagick for image processing:

Checking available libraries:

1. Go to Tools → Site Health → Info → Media Handling
2. Check which image library is active (GD or ImageMagick)
3. Ensure at least one is installed and functioning

If no image library is available:

• Contact your hosting provider to install GD Library or ImageMagick
• Most modern hosts have these pre-installed
• Without an image library, uploads will fail

Testing upload functionality

Systematic testing helps isolate the problem:

Test 1: Standard WordPress upload

1. Go to Media → Add New
2. Upload a regular image (2-3MB)
3. If this fails, it’s a WordPress/server issue, not Annotatr

Test 2: Small screenshot in Annotatr

1. Create a note on a simple page
2. Select a small element (e.g., a button)
3. If this succeeds, the issue is likely image size/memory

Test 3: Comment attachment

1. Open an existing note
2. Try uploading a small image as a comment attachment
3. If this fails but screenshots work, check file type restrictions

Security plugin interference

Some security plugins block uploads or modify file handling:

• Temporarily disable security plugins (Wordfence, iThemes Security)
• Test upload functionality
• If uploads work, re-enable and adjust security plugin settings
• Whitelist Annotatr’s upload endpoints if necessary

Quick checklist

If images aren’t uploading, verify these in order: PHP memory_limit ≥ 256MB, upload_max_filesize ≥ 10MB, post_max_size ≥ 12MB, uploads directory permissions = 755/775, sufficient disk space available, GD Library or ImageMagick installed, and standard WordPress media uploads working.