Troubleshooting Guide

Common issues and solutions for Vimeify. Use this guide to quickly resolve problems.

Connection Issues

Cannot Connect to Vimeo API

Symptoms:

"Invalid API credentials" error
"Could not connect to Vimeo" message
Connection status shows disconnected

Solutions:

Verify Access Token

Settings → Connection
- Check Access Token is current and valid
- No extra spaces when copying
- Token has all required scopes

Test API Connection
bash
```
wp vimeify test-connection
```
Regenerate Access Token
- Go to Vimeo Developer Portal
- Your Apps → Select app
- Authentication tab
- Generate new access token
- Update in WordPress
Check Required Scopes
- Public ✓
- Private ✓
- Upload ✓
- Edit ✓
- Delete ✓
Verify Server Can Reach Vimeo
bash
```
curl -I https://api.vimeo.com
```

Common Causes:

Expired access token
Wrong credentials
Missing API scopes
Firewall blocking Vimeo
SSL certificate issues

API Rate Limit Exceeded

Symptoms:

"Rate limit exceeded" error
Sync stops working
Uploads fail with quota error

Solutions:

Check Current Quota
bash
```
wp vimeify sync info
```
Wait for Reset
- Quotas reset hourly
- Wait 1 hour and retry
Upgrade Vimeo Plan
- Free: 1,000 calls/hour
- Plus/Pro: Higher limits
- Check vimeo.com/upgrade

Optimize Sync Settings

Settings → Sync
- Change to "Update existing only"
- Reduces API calls significantly

Manually Trigger After Reset

bash

# Wait for hour to pass, then:
wp vimeify sync all

Upload Issues

Upload Fails Immediately

Symptoms:

Error before upload starts
"Upload failed" message instantly
No progress bar appears

Solutions:

Check File Type
- Allowed: MP4, MOV, AVI, WMV, MKV
- Convert unsupported formats
Verify File Size
- Check PHP limits:
bash
```
wp vimeify config php-limits
```
- Check Vimeo plan limits
- Free: 500MB per file
- Plus: 5GB per file
- Pro/Business: 25GB per file
Test API Connection
bash
```
wp vimeify test-connection
```
Check User Permissions
- User has upload_to_vimeo capability
- Not a subscriber/contributor

Review Error Logs

bash

tail -f wp-content/debug.log
tail -f wp-content/uploads/vimeify/cron.log

Upload Stalls or Stops

Symptoms:

Progress bar stops moving
Stuck at specific percentage
"Upload timeout" error

Solutions:

Check Internet Connection
- Stable connection required
- Test with speed test
- Try wired connection

Reduce Chunk Size

php

// In functions.php
add_filter( 'vimeify_chunk_size', function() {
    return 2 * 1024 * 1024; // 2MB chunks
} );

Increase PHP Timeouts

ini

# In php.ini or .htaccess
max_execution_time = 600
max_input_time = 600

Try Different Browser
- Chrome/Firefox recommended
- Clear browser cache
- Disable extensions

Use WP-CLI (Server Upload)

bash

# Upload from server
wp vimeify upload /path/to/video.mp4 \
  --title="My Video" \
  --privacy=private

Video Not Appearing After Upload

Symptoms:

Upload succeeds
No video in WordPress
Can't find video post

Solutions:

Check Trash Folder
```
Vimeify → Videos → Trash
```
Run Manual Sync
bash
```
wp vimeify sync metadata
```

Check Auto-Publish Setting

Settings → Upload
- Verify "Auto-publish videos" enabled
- If disabled, check Drafts

Verify Vimeo Upload
- Log into vimeo.com
- Check if video exists
- Note Vimeo video ID
Check for PHP Errors
bash
```
tail -f wp-content/debug.log
```

Sync Issues

Automatic Sync Not Running

Symptoms:

Videos not syncing
New Vimeo videos don't appear
Deleted videos still show

Solutions:

Check Action Scheduler

Tools → Scheduled Actions
- Search "vimeify"
- Verify actions scheduled
- Check for failures

Verify WP Cron
bash
```
wp cron event list | grep vimeify
```
Manually Trigger Sync
bash
```
wp vimeify sync all
```

Run Action Scheduler

bash

wp action-scheduler run --hooks=vimeify_action_metadata_sync

Check Server Cron

bash

# If using server cron instead of WP cron
crontab -l | grep wp-cron

Sync Stuck or Incomplete

Symptoms:

Sync starts but doesn't finish
Progress shows same percentage
Some videos don't sync

Solutions:

Check Sync Status
bash
```
wp vimeify sync info
```

Reset Sync State

bash

wp vimeify sync metadata --fresh
wp vimeify sync status --fresh

Check API Quota
- May be waiting for quota reset
- Check quota in sync info
- Wait 1 hour if exceeded

Review Sync Logs

bash

tail -f wp-content/uploads/vimeify/cron.log

Disable Other Plugins
- Test with default theme
- Deactivate other plugins
- Check for conflicts

Videos Syncing Slowly

Symptoms:

Sync takes very long
Only few videos sync per cycle

Solutions:

Increase Per Page

php

add_filter( 'vimeify_sync_per_page', function() {
    return 200; // Instead of default 100
} );

Check Server Performance
- CPU usage
- Available memory
- Disk I/O
Optimize Database
bash
```
wp db optimize
```
Disable Heavy Plugins
- Temporarily disable heavy plugins
- Check if sync speeds up

Display Issues

Video Player Not Showing

Symptoms:

Blank space where video should be
"Video unavailable" message
Black rectangle instead of player

Solutions:

Check Video Privacy
- Verify privacy setting on Vimeo
- Private videos need authentication
- Use Unlisted or Public for embedding
Test Direct Vimeo Link
- Get Vimeo URL from video
- Open in browser
- Verify video plays on vimeo.com
Check Browser Console
- F12 → Console tab
- Look for errors
- Screenshot errors for support
Clear All Caches
- WordPress cache plugins
- Server cache
- CDN cache
- Browser cache
Test with Default Theme
- Switch to Twenty Twenty-Four
- Check if video displays
- Theme conflict if it works

Gallery Not Displaying

Symptoms:

Empty gallery area
No videos show in gallery
Gallery shortcode shows nothing

Solutions:

Verify Gallery Has Videos
```
Edit Gallery → Check video count
```

For Folder Sync Galleries

bash

# Check Vimeo folder has videos
# Run sync
wp vimeify sync metadata

Check Gallery Published

Gallery status must be "Published"
Not Draft or Private

Test Gallery ID

[vimeify_gallery id="CORRECT_ID"]
- Verify ID is correct
- Check in Vimeify → Galleries

Check JavaScript Console
- F12 → Console
- Look for gallery-related errors

Styling Issues

Symptoms:

Videos display but look wrong
Layout broken
Overlapping elements

Solutions:

Check CSS Conflicts

F12 → Inspect element
- Check CSS being applied
- Look for !important overrides
- Note conflicting styles

Add Custom CSS

css

/* Fix common conflicts */
.vimeify-video iframe {
    max-width: 100% !important;
    height: auto !important;
}

Regenerate Styles

For Elementor:

Elementor → Tools → Regenerate CSS

For Bricks:

Bricks → Settings → Clear Cache

Test with Theme Defaults
- Switch to default theme temporarily
- If it works, theme CSS conflict

Check for Missing Assets

F12 → Network tab
- Look for 404 errors
- Note missing CSS/JS files

Integration Issues

Page Builder Widgets Missing

Symptoms:

Can't find Vimeify widgets
Widgets not in panel
Integration not working

Solutions:

Verify Plugin Active
```
Plugins → Check Vimeify activated
```
Clear Builder Cache
- Elementor: Tools → Regenerate CSS
- Bricks: Settings → Clear Cache
Check WordPress Version
- WordPress 5.8+ required
- Update if outdated
Reinstall Vimeify
- Deactivate (don't delete)
- Reactivate
- Check if widgets appear
Check for Conflicts
- Disable other plugins
- Test with default theme
- Re-enable one by one

Form Upload Not Working (Pro)

Symptoms:

Upload field doesn't appear
Upload fails in form
No progress shown

Solutions:

Verify Pro Active

Plugins → Check Vimeify Pro activated
Check for "Pro" badge in menu

Check License

Vimeify → Settings → License
- License must be activated
- Not expired

Test Form Without Upload
- Remove upload field
- Test form submits
- Add upload field back
Check Browser Console
- F12 → Console
- Look for JavaScript errors
- Note errors for support
Test with Default Form
- Create simple test form
- Just upload field + submit
- If works, issue in complex form

Performance Issues

Slow Admin Dashboard

Symptoms:

WordPress admin slow
Vimeify pages load slowly
Timeout errors

Solutions:

Check Video Count
- Many videos (1000+) can slow admin
- Use pagination
- Filter/search instead of viewing all

Disable Heavy Features

php

// Disable thumbnail generation
add_filter( 'vimeify_generate_thumbnails', '__return_false' );

Increase PHP Limits

ini

memory_limit = 512M
max_execution_time = 300

Optimize Database

bash

wp db optimize
wp transient delete --all

Use Object Caching
- Install Redis or Memcached
- Install object cache plugin
- Significantly improves performance

Sync Using Too Many Resources

Symptoms:

Server CPU high during sync
Site slow when sync runs
Memory limit errors

Solutions:

Reduce Sync Frequency

php

// Custom sync schedule (30 min instead of 10)
add_filter( 'vimeify_metadata_sync_interval', function() {
    return 30 * MINUTE_IN_SECONDS;
} );

Process Fewer Videos

php

add_filter( 'vimeify_sync_per_page', function() {
    return 25; // Instead of 100
} );

Sync During Off-Hours

php

// Only sync between 1am-6am
add_filter( 'vimeify_should_run_sync', function( $should_run ) {
    $hour = (int) date( 'G' );
    return $hour >= 1 && $hour <= 6;
} );

Use WP-CLI for Manual Sync

bash

# Run sync manually during maintenance
wp vimeify sync all

Database & Data Issues

Missing Video Metadata

Symptoms:

Video exists but missing details
No thumbnail
No duration
No embed URL

Solutions:

Resync Video

bash

# Resync specific video
wp vimeify sync video POST_ID

# Or resync all
wp vimeify sync metadata --fresh

Check Vimeo Data
- Log into vimeo.com
- Verify video has metadata there
- If missing on Vimeo, add it
Re-Upload Video
- If metadata still missing
- May be corrupted
- Delete and re-upload

Duplicate Videos

Symptoms:

Same video appears twice
Multiple posts for one Vimeo video

Solutions:

Identify Duplicates

bash

wp post list --post_type=vimeify-video \
  --meta_key=_vimeify_vimeo_id \
  --format=table

Delete Duplicates
- Keep original
- Delete duplicates from Trash
- Permanently delete

Prevent Future Duplicates

Settings → Sync
- Use "Update existing only" mode

Migration Issues

Symptoms:

Upgrading from old version
Database errors
Missing data after update

Solutions:

Run Migrations

Vimeify → Tools → Database Migration
- Click "Run Migration"

Check Migration Status
bash
```
wp vimeify migrations status
```

Backup Before Migration

bash

# Backup database
wp db export vimeify-backup.sql

Contact Support
- If migration fails
- Don't try multiple times
- Provide error messages

Getting More Help

Enable Debug Mode

Get detailed error information:

php

// In wp-config.php
define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );
define( 'VIMEIFY_DEVELOPMENT', true );

Check logs:

bash

tail -f wp-content/debug.log
tail -f wp-content/uploads/vimeify/cron.log

Gather System Information

Before contacting support, gather:

bash

# WordPress version
wp core version

# PHP version and limits
wp vimeify config php-info

# Plugin version
wp plugin list --name=vimeify

# Sync status
wp vimeify sync info

# Recent errors
tail -n 100 wp-content/debug.log

Test in Clean Environment

Backup Site
Disable Other Plugins
Switch to Default Theme
Test Issue
Re-enable One by One

Contact Support

Free Version:

Pro Version:

Email: [email protected]
Private ticket system
Include:
- WordPress version
- PHP version
- Error messages
- Steps to reproduce
- System info

Get Support →

Quick Reference

Common Commands

bash

# Test connection
wp vimeify test-connection

# Run sync
wp vimeify sync all
wp vimeify sync metadata
wp vimeify sync status

# Sync info
wp vimeify sync info

# Fresh sync
wp vimeify sync all --fresh

# System info
wp vimeify config php-info

Common Filters

php

# Chunk size
add_filter( 'vimeify_chunk_size', function() { return 5 * 1024 * 1024; } );

# Sync per page
add_filter( 'vimeify_sync_per_page', function() { return 50; } );

# Disable thumbnails
add_filter( 'vimeify_generate_thumbnails', '__return_false' );

Debug Locations

Error Logs:
- wp-content/debug.log
- wp-content/uploads/vimeify/cron.log

Cache:
- wp-content/cache/vimeify/

Temporary Files:
- wp-content/uploads/vimeify/temp/

FAQ - Frequently asked questions
Support - Get help
Installation - Setup guide
CLI Commands - Command reference

Troubleshooting Guide ​

Connection Issues ​

Cannot Connect to Vimeo API ​

API Rate Limit Exceeded ​

Upload Issues ​

Upload Fails Immediately ​

Upload Stalls or Stops ​

Video Not Appearing After Upload ​

Sync Issues ​

Automatic Sync Not Running ​

Sync Stuck or Incomplete ​

Videos Syncing Slowly ​

Display Issues ​

Video Player Not Showing ​

Gallery Not Displaying ​

Styling Issues ​

Integration Issues ​

Page Builder Widgets Missing ​

Form Upload Not Working (Pro) ​

Performance Issues ​

Slow Admin Dashboard ​

Sync Using Too Many Resources ​

Database & Data Issues ​

Missing Video Metadata ​

Duplicate Videos ​

Migration Issues ​

Getting More Help ​

Enable Debug Mode ​

Gather System Information ​

Test in Clean Environment ​

Contact Support ​

Quick Reference ​

Common Commands ​

Common Filters ​

Debug Locations ​

Related ​

Troubleshooting Guide

Connection Issues

Cannot Connect to Vimeo API

API Rate Limit Exceeded

Upload Issues

Upload Fails Immediately

Upload Stalls or Stops

Video Not Appearing After Upload

Sync Issues

Automatic Sync Not Running

Sync Stuck or Incomplete

Videos Syncing Slowly

Display Issues

Video Player Not Showing

Gallery Not Displaying

Styling Issues

Integration Issues

Page Builder Widgets Missing

Form Upload Not Working (Pro)

Performance Issues

Slow Admin Dashboard

Sync Using Too Many Resources

Database & Data Issues

Missing Video Metadata

Duplicate Videos

Migration Issues

Getting More Help

Enable Debug Mode

Gather System Information

Test in Clean Environment

Contact Support

Quick Reference

Common Commands

Common Filters

Debug Locations

Related