Skip to content

Adam Greenwell

Troubleshooting Guide

Common issues and solutions for ListenUp.

Audio Not Playing

Symptoms: Player appears but audio doesn't play, error messages in browser console.

Check Audio Generation Status

  1. Edit the post in WordPress
  2. Find the ListenUp meta box
  3. Check the status:
    • No audio – Generate audio first
    • Generating… – Wait for completion
    • Ready – Audio should be playable
    • Error – See error message for details

Check Browser Console

  1. Open browser developer tools (F12)
  2. Go to Console tab
  3. Look for error messages containing "ListenUp" or "MEDIA_ELEMENT_ERROR"

Common Console Errors

MEDIA_ELEMENT_ERROR: Format error

  • Audio file may be corrupted
  • Try regenerating the audio

403 Forbidden on audio URL

  • Signed URL may have expired (cloud storage)
  • Clear page cache and refresh
  • Check cloud storage credentials

404 Not Found

  • Audio file may have been deleted
  • Regenerate the audio

Verify Audio File Exists

For local storage:

  1. Connect via FTP/SFTP
  2. Navigate to wp-content/uploads/listenup-audio/
  3. Look for files matching the post ID

For cloud storage:

  1. Log into your cloud provider console
  2. Check your bucket for the audio files

Check Plugin Conflicts

  1. Deactivate other plugins one by one
  2. Test audio playback after each deactivation
  3. Identify the conflicting plugin

Generation Errors

Symptoms: "Generate Audio" fails with an error message.

Invalid or Expired API Key

Error: "API request failed" or "401 Unauthorized"

Solution:

  1. Go to Settings → ListenUp
  2. Verify your Murf.ai API key is correct
  3. Check your Murf.ai account is active
  4. Generate a new API key if needed

API Rate Limiting

Error: "429 Too Many Requests"

Solution:

  • Wait a few minutes before trying again
  • Check your Murf.ai plan limits
  • Consider upgrading your Murf.ai plan

Content Too Long

Error: Content should auto-chunk, but if it fails:

Solution:

  1. Check for unusual content (very long words, special characters)
  2. Try removing problematic content
  3. Enable debug logging to identify the issue

Network Timeout

Error: "Request timeout" or connection errors

Solution:

  1. Check your server's internet connectivity
  2. Verify Murf.ai service is operational
  3. Try again later if Murf.ai is experiencing issues
  4. Increase PHP timeout if consistently timing out

Server Memory Issues

Error: PHP memory errors during generation

Solution:

  1. Increase PHP memory limit in wp-config.php: 
    define('WP_MEMORY_LIMIT', '256M');
  2. Contact your hosting provider if unable to increase

Cloud Storage Issues

Symptoms: Audio not uploading to cloud, signed URL errors.

Expired Signed URLs

Symptoms: Audio plays briefly then stops, or shows 403 error after page was cached.

Cause: Page caching stored a signed URL that expired.

Solution: This was fixed in version 1.5.13 and is included in the current 1.5.135 release. Update to the latest version. URLs are now fetched fresh via AJAX when the player initializes.

Invalid Credentials

Error: "Access Denied" or authentication errors

Solution:

  1. Go to Settings → ListenUp → Cloud Storage
  2. Verify all credentials are correct
  3. Re-enter credentials if needed
  4. Check IAM permissions for your access key

Bucket Configuration

Error: "Bucket not found" or "NoSuchBucket"

Solution:

  1. Verify bucket name is correct (case-sensitive)
  2. Check bucket exists in your cloud console
  3. Verify bucket region matches configuration

Permission Issues

Error: "Access Denied" when uploading

Required S3 Permissions:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:PutObject",
        "s3:GetObject",
        "s3:DeleteObject",
        "s3:ListBucket"
      ],
      "Resource": [
        "arn:aws:s3:::your-bucket-name",
        "arn:aws:s3:::your-bucket-name/*"
      ]
    }
  ]
}

CORS Configuration

Error: CORS errors in browser console

Solution: Configure CORS on your bucket. For S3:

[
  {
    "AllowedHeaders": ["*"],
    "AllowedMethods": ["GET", "HEAD"],
    "AllowedOrigins": ["https://yoursite.com"],
    "ExposeHeaders": []
  }
]

Learn more about Cloud Storage →

Player Not Appearing

Symptoms: No audio player visible on posts with audio.

Check Auto Placement Settings

  1. Go to Settings → ListenUp
  2. Check Auto Placement setting
  3. Ensure it includes your post type (Posts, Pages, or Both)
  4. Check Placement Position (Before/After Content)

Verify Audio Exists

  1. Edit the post
  2. Check ListenUp meta box shows "Ready" status
  3. If no audio, generate it first

Check for Theme Conflicts

Some themes may hide or conflict with the player:

  1. Switch to a default theme (Twenty Twenty-Four)
  2. Test if player appears
  3. If working, issue is theme-related

Check Player Display Settings

If the player appears but the controls are not what you expect:

  1. Go to Settings → ListenUp → Display
  2. Confirm the player layout is set to Featured player or Compact controls
  3. Check whether skip controls or the playback speed selector are hidden
  4. Confirm the default playback speed is set to the expected value

Check Shortcode Syntax

If using manual placement:

Correct: [listenup]

Common mistakes:

  • Wrong brackets: (listenup)
  • Extra spaces: [ listenup ]
  • Wrong case: [ListenUp]

JavaScript Errors

  1. Open browser console (F12)
  2. Look for JavaScript errors
  3. May indicate script conflicts with other plugins/themes

Check for Page Builders

Some page builders may strip shortcodes. Try:

  1. Using a Custom HTML block
  2. Adding shortcode in theme template
  3. Using automatic placement instead

Download Issues

Symptoms: Download button missing or downloads fail.

Download Button Not Visible

Cause: Download restrictions are enabled

Solution:

  1. Go to Settings → ListenUp
  2. Check Download Restriction setting
  3. Set to "Allow All" if you want everyone to download
  4. Set to "Logged In Only" for authenticated users

Download Fails or Corrupted File

Cause: File concatenation issue (for chunked content)

Solution:

  1. Check audio format supports chunking (MP3, OGG work best)
  2. Try regenerating the audio
  3. Check server has enough memory for concatenation

Large File Download Timeout

Cause: Long content with many chunks takes time to concatenate

Solution:

  1. Increase PHP max_execution_time
  2. Use cloud storage (serves pre-concatenated files)
  3. Consider shorter content

Pronunciation Issues

Symptoms: Words pronounced incorrectly despite dictionary rules.

Rules Not Applied

  1. Verify pronunciation dictionary is enabled
  2. Check rules are saved correctly
  3. Regenerate audio – rules only apply to new generations

Check Rule Format

SAY_AS type:

  • Word: AWS
  • Pronunciation: Amazon Web Services
  • Type: SAY_AS

IPA type:

  • Word: live
  • Pronunciation: laɪv
  • Type: IPA

Case Sensitivity

Pronunciation rules are case-sensitive. "AWS" won't match "aws" in content.

Word Boundaries

Rules match whole words. "API" won't change "APIs" unless you add both.

Learn more about Pronunciation →

Pre-roll Issues

Symptoms: Pre-roll audio not playing or not generating.

Pre-roll Not Playing

  1. Check pre-roll is configured in Settings → ListenUp → Pre-roll
  2. Verify pre-roll file exists (if uploaded)
  3. Regenerate audio with pre-roll enabled

Pre-roll Generation Failed

Cause: Same issues as regular audio generation

Solution:

  1. Check API key is valid
  2. Verify pre-roll text isn't too long
  3. Try generating with different text

Pre-roll File Missing

If you uploaded a file that's now missing:

  1. Re-upload the pre-roll audio
  2. Save settings
  3. Regenerate audio for affected posts

Performance Issues

Symptoms: Slow audio generation, site slowdown.

Slow Generation

Causes:

  • Long content (many chunks)
  • Slow Murf.ai API response
  • Server network issues

Solutions:

  • Consider shorter content or summaries
  • Generate during off-peak hours
  • Use WP-CLI for bulk generation in background

Site Slowdown

Cause: Large audio files or many AJAX requests

Solutions:

  1. Enable cloud storage to offload files
  2. Optimize audio format (MP3 is most efficient)
  3. Limit audio library shortcode results

Memory Issues During Bulk Operations

Solution:

# Use batch size flag with WP-CLI
wp listenup generate --all --batch-size=5

WP-CLI Issues

Symptoms: Commands fail or produce errors.

Command Not Found

Error: 'listenup' is not a recognized command

Solution:

  1. Verify plugin is activated
  2. Run wp plugin list to confirm
  3. Clear WP-CLI cache: wp cli cache clear

Permission Errors

Error: Cannot write to uploads directory

Solution:

  1. Check directory permissions
  2. Run as correct user: sudo -u www-data wp listenup generate --all

Timeout on Large Sites

Error: Command times out during bulk operations

Solution:

  1. Use smaller batch sizes
  2. Run in background with screen/tmux
  3. Process by post type or date range

Debug Mode

Enable debugging to get more detailed error information:

  1. Add to wp-config.php:
define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);
define('WP_DEBUG_DISPLAY', false);

  1. Check /wp-content/debug.log for ListenUp errors

  2. Look for entries containing "ListenUp" or "listenup"

Still Having Issues?

If you've tried these solutions and still have problems:

  1. Check the WordPress.org forums – Search for similar issues
  2. Post a support request – Include:
    • WordPress version
    • PHP version
    • Plugin version
    • Error messages (from browser console and debug.log)
    • Steps to reproduce

WordPress.org Support Forums →

Back to Documentation Index →