Troubleshooting

Common issues and solutions when working with MediaProc CLI.

Installation Issues

Command Not Found

Problem: After installing MediaProc, running mediaproc returns "command not found".

Solutions:

Check global npm bin directory:

Ensure this directory is in your PATH. Add to your ~/.bashrc or ~/.zshrc:

export PATH="$PATH:/usr/local/bin"

Reinstall globally:

Use npx as alternative:

Permission Errors

Problem: Getting EACCES or permission denied errors during installation.

Solutions:

Fix npm permissions (recommended):

Use sudo (not recommended):

Plugin Issues

Plugin Not Found

Problem: After adding a plugin, commands return "plugin not found" error.

Check installed plugins:

Reinstall the plugin:

Verify plugin installation path:

Plugin Installation Fails

Problem: Plugin installation fails with dependency errors.

Common causes:

• Missing system dependencies (FFmpeg, Sharp)
• Network issues
• Incompatible Node.js version

Check Node.js version:

MediaProc requires Node.js 16 or higher.

Install system dependencies:

macOS:

Ubuntu/Debian:

Windows:

Processing Errors

FFmpeg Not Found

Problem: Video or audio commands fail with "FFmpeg not found" error.

Install FFmpeg:

If not installed, see FFmpeg installation guide.

Specify FFmpeg path manually:

Out of Memory Errors

Problem: Processing large files causes memory errors.

Solutions:

Increase Node.js memory limit:

Process in smaller batches:

Instead of:

Do:

Use streaming mode for video:

File Not Found Errors

Problem: MediaProc can't find input files.

Common causes:

• Wrong working directory
• Special characters in filenames
• Glob patterns not expanding

Use absolute paths:

Quote filenames with spaces:

Check working directory:

Format Issues

Unsupported Format

Problem: Getting "unsupported format" errors.

Check supported formats:

Convert to supported format first:

Codec Issues

Problem: Output video won't play in certain players.

Use widely compatible codecs:

Check codec support:

Performance Issues

Slow Processing

Problem: Processing takes much longer than expected.

Enable hardware acceleration:

Use fast mode (stream copy):

Process in parallel:

Reduce quality for faster processing:

CPU Usage Too High

Problem: MediaProc uses 100% CPU.

Limit concurrent operations:

Nice the process (lower priority):

Configuration Issues

Settings Not Persisting

Problem: Configuration changes don't persist between runs.

Check config file location:

Set config explicitly:

Reset to defaults:

Common Error Messages

"ENOSPC: no space left on device"

Solution: Free up disk space before processing.

"Error: spawn ENOMEM"

Solution: Reduce memory usage or increase available memory.

"Error: Command failed with exit code 1"

Run with verbose flag to see full error:

Debug Mode

Enable Detailed Logging

Save Debug Log to File

Getting Help

Check Command Help

Validate Configuration

Report an Issue

If you've found a bug or issue not covered here:

1. Check existing issues: GitHub Issues
2. Collect debug information:
   Terminal

   $ mediaproc --version

   $ node --version

   $ npm --version

   $ ffmpeg -version
3. Create a new issue with reproduction steps

Platform-Specific Issues

macOS

Gatekeeper blocking FFmpeg:

M1/M2 Rosetta issues:

Windows

PowerShell execution policy:

Path separator issues:

Use forward slashes or escape backslashes:

Linux

Missing shared libraries:

Best Practices

Always test commands first:

Keep backups of original files

Use descriptive output names

Monitor disk space for batch operations

Update MediaProc regularly:

Related Resources

• CLI Overview - Understanding MediaProc architecture
• Plugin Architecture - How plugins work
• Community Support - Get help from the community