Troubleshooting

This guide covers common problems you might encounter when using Aceplay and how to solve them.

Enable verbose mode

For any troubleshooting, start by enabling verbose logging:

aceplay play acestream://... --verbose

Or set it permanently:

verbose: true

This shows detailed information about:

Configuration loading
Engine detection and startup
Stream connection process
Player launching

Common issues

Engine not found

Error: acestream-engine not found in PATH

Cause: Aceplay can’t locate the acestreamengine executableSolutions:

Install acestream-engine: Visit acestream.org and follow installation instructions for your distribution.
Verify installation:
```
which acestreamengine
```
Should output the path to the binary.
Check PATH:
```
echo $PATH
```
Ensure the directory containing acestreamengine is in your PATH.

Add to PATH temporarily:

export PATH=$PATH:/path/to/acestream/bin

Or use a pre-started engine: Start the engine manually in another terminal:
```
acestreamengine --client-console --http-port 6878
```
Then run Aceplay normally.

Player not found

Error: player 'mpv' not found

Cause: The configured video player is not installedSolutions:

Install the player:
sudo pacman -S mpv

Use a different player:

aceplay play acestream://... --player vlc

Check available players:
```
which mpv
which vlc
which ffplay
```
List installed players: Aceplay detects available players automatically. Run the setup wizard to see what’s available:
```
aceplay interactive
```

Stream timeout

Error: failed to get stream: context deadline exceeded

Cause: Stream took longer than the configured timeout to become readySolutions:

Increase timeout:

aceplay play acestream://... --timeout 120s

Set permanently in config:
```
timeout: 120s
```
Check stream is valid: Some content IDs may be inactive or invalid. Try a different stream.
Check engine is working:
```
curl http://localhost:6878/
```
Check internet connection: Acestream requires good connectivity to peers.
Wait for peers: Some streams need time to find peers. Be patient and try again.

Connection refused

Error: connection refused

Cause: Can’t connect to acestream-engineSolutions:

Check engine is running:
```
ps aux | grep acestreamengine
```
Check port is correct:
```
netstat -tlnp | grep 6878
```
Verify engine responds:
```
curl http://localhost:6878/
```

Start engine manually:

acestreamengine --client-console --http-port 6878

Check for port conflicts: If something else is using port 6878:

aceplay play acestream://... --engine-port 8080

And start engine on that port:

acestreamengine --client-console --http-port 8080

Invalid URL

Error: invalid URL

Cause: The acestream URL format is incorrectSolutions:

Check URL format: Valid formats:
- acestream://94c2fd8fb9bc8f2fc71a2cbe9d4b866f227a0209
- 94c2fd8fb9bc8f2fc71a2cbe9d4b866f227a0209 (content ID only)

URL must be 32-40 hex characters:

# Valid (40 chars)
aceplay play acestream://94c2fd8fb9bc8f2fc71a2cbe9d4b866f227a0209

# Invalid (too short)
aceplay play acestream://94c2fd8f

Decode URL-encoded links: If you copied from a browser, it might be URL-encoded:

# Firefox may encode as
acestream%3A%2F%2F94c2fd8fb9bc8f2fc71a2cbe9d4b866f227a0209

# Aceplay handles this automatically, but ensure it's properly quoted
aceplay play "acestream://..."

Config file errors

Error: error reading configuration

Cause: Config file has invalid YAML syntaxSolutions:

Check config file syntax:
```
cat ~/.config/aceplay/config.yaml
```
Validate YAML: Common mistakes:
- Incorrect indentation (use spaces, not tabs)
- Missing colons
- Quotes in wrong places
Valid config:
```
player: mpv
engine:
  host: localhost
  port: 6878
timeout: 60s
hls: false
verbose: false
```
Reset config: Backup and delete the config file:
```
mv ~/.config/aceplay/config.yaml ~/.config/aceplay/config.yaml.backup
```
Run Aceplay - it will create a new config:
```
aceplay
```
Use the interactive editor:
```
aceplay config edit
```

Browser integration not working

Browser doesn't open acestream:// links

Cause: Protocol handler not registered or not recognizedSolutions:

Re-register protocol:
```
aceplay install
```
Restart browser Close and reopen your browser after registering.

Check desktop file:

cat ~/.local/share/applications/aceplay.desktop

Should contain:

MimeType=x-scheme-handler/acestream;

Verify default handler:

xdg-mime query default x-scheme-handler/acestream

Should output: aceplay.desktop

Set as default manually:

xdg-mime default aceplay.desktop x-scheme-handler/acestream

Update desktop database:

update-desktop-database ~/.local/share/applications

For KDE users:
```
kbuildsycoca5
```

Player issues

Player opens but no video

Cause: Various player-specific issuesSolutions:

Check stream URL is valid: Enable verbose mode to see the stream URL:

aceplay play acestream://... --verbose

Look for a line like:

Starting playback: http://localhost:6878/...

Test URL directly: Copy the stream URL and test in player:
```
mpv "http://localhost:6878/ace/manifest.m3u8?id=..."
```

Try different player:

aceplay play acestream://... --player vlc

Try HLS mode:
```
aceplay play acestream://... --hls
```
Check codec support: Ensure your player supports the stream codec. Install codec packages:
```
# Arch
sudo pacman -S ffmpeg

# Debian/Ubuntu
sudo apt install ffmpeg
```

Performance issues

Buffering/stuttering

Stream keeps buffering

Solutions:

Increase player cache: For mpv (already has --cache=yes by default in Aceplay) For VLC (already has --network-caching=3000 by default)
Try HLS mode:
```
aceplay play acestream://... --hls
```
Check internet speed: Acestream requires good download speed and peer availability.
Wait for more peers: Watch the stream statistics:
```
Status: dl | ↓ 1.2 MB/s | ↑ 256 KB/s | Peers: 15
```
More peers = better performance.
Check CPU usage:
```
top
```
If CPU is maxed out, try a lighter player or lower quality stream.

High latency

Stream is delayed by 10-20 seconds

Cause: Normal for HLS mode or network conditionsSolutions:

Use direct mode instead of HLS:

aceplay play acestream://... # without --hls

Accept the latency: Acestream P2P protocol has inherent latency. Some delay is normal.
Reduce player buffering: This is player-dependent and may cause stuttering.

Getting help

If you’re still experiencing issues:

Check the logs: Run with verbose mode and save output:

aceplay play acestream://... --verbose 2>&1 | tee aceplay.log

Verify versions:

aceplay version
acestreamengine --version
mpv --version

Check system:
```
uname -a
cat /etc/os-release
```
File an issue: Visit github.com/crstian19/aceplay/issues Include:
- Aceplay version
- OS and version
- Full error message
- Steps to reproduce
- Verbose log output

Quick diagnostic checklist

Run through this checklist to diagnose most issues:

acestreamengine is installed and in PATH
Video player (mpv/vlc/ffplay) is installed
Engine is running: curl http://localhost:6878/
Stream URL is valid (40 hex chars)
Config file is valid YAML
No port conflicts on 6878
Firewall allows acestream traffic
Good internet connection
Verbose mode enabled for debugging

Reference

Error handling: cmd/main.go:161-276
Engine detection: internal/acestream/client.go:146-161
Player validation: internal/player/player.go:42-56
URL parsing: pkg/acestream/url.go

Get Started

Usage

Configuration

Advanced

Development

Troubleshooting

Enable verbose mode

Common issues

Engine not found

Player not found

Stream timeout

Connection refused

Invalid URL

Config file errors

Browser integration not working

Player issues

Performance issues

Buffering/stuttering

High latency

Getting help

Quick diagnostic checklist

Reference

Build docs developers (and LLMs) love

Get Started

Usage

Configuration

Advanced

Development

​Enable verbose mode

​Common issues

​Engine not found

​Player not found

​Stream timeout

​Connection refused

​Invalid URL

​Config file errors

​Browser integration not working

​Player issues

​Performance issues

​Buffering/stuttering

​High latency

​Getting help

​Quick diagnostic checklist

​Reference

Build docs developers (and LLMs) love

Enable verbose mode

Common issues

Engine not found

Player not found

Stream timeout

Connection refused

Invalid URL

Config file errors

Browser integration not working

Player issues

Performance issues

Buffering/stuttering

High latency

Getting help

Quick diagnostic checklist

Reference