Repository navigation
Troubleshooting
Start with the quick checks, then go to the section that matches what you see.
curl http://127.0.0.1:6878/healthz # is the daemon up?
curl http://127.0.0.1:6878/streams # what is running?
curl "http://127.0.0.1:6878/streams/ace/${CONTENT_ID:?set a content id}/status" # peers, bitrate, buffer
outpace --version # what you are running- Try a different stream that you know is live. A dead channel looks exactly like a network problem.
- Turn off full-tunnel VPNs, Cloudflare WARP in particular, and test again.
- Look at the logs:
docker compose logs -f,docker logs -f outpaceorjournalctl -u outpace -f.
Outpace validates all settings before it opens any listener, and names the problem:
| Message contains | Fix |
|---|---|
invalid OUTPACE_X: "..."; expected one of: 1, true, 0, false |
Use exactly 1, true, 0 or false. |
... must be >= ..., ... must be <= ...
|
A value is out of range or contradicts another one. See Configuration. |
OUTPACE_CACHE_DIR ... is not a dedicated Outpace cache |
The disk-cache directory isn't empty and has no .outpace-cache marker. Point it at an empty directory, or create the marker only if everything in it may be deleted. |
OUTPACE_CACHE_DIR must not equal or contain OUTPACE_DATA_DIR |
Use a cache directory inside the data directory, or somewhere separate. |
exceeds this target's conservative ...-byte memory-cache limit |
Lower OUTPACE_SEED_STORE_BYTES, or use OUTPACE_CACHE_TYPE=disk. Common on 32-bit. |
broadcast_store_too_small |
OUTPACE_SEED_STORE_BYTES must hold at least one full broadcast piece. |
invalid_broadcast_options, invalid_source_config
|
Fix the JSON in OUTPACE_BROADCAST_OPTIONS or OUTPACE_BROADCAST_SOURCES. |
private_mode_conflict_*, local_descriptors_require_private_mode
|
See Private Peer Mode. |
srt_feature_unavailable |
OUTPACE_SRT_BIND is set, but this binary was built without SRT. |
srt_unsafe_passphrase_file |
Fix the key file's owner and permissions (chmod 600, owned by the daemon user). |
| Address already in use | Another process (often the old AceStream engine) holds 6878, 1935 or 8621. |
With Compose, remember that most settings must go in compose.override.yml. If a change in
.env seems to do nothing, that's usually why; see
Deployment.
Outpace keeps recent productive peer hints in its cache directory (OUTPACE_CACHE_DIR,
<data dir>/cache by default) to help later starts. With OUTPACE_CACHE_TYPE=disk the
startup cache wipe clears them, so they help only within one run.
On Linux and Android, this works through execute-only parent directories, including
Android app storage and Termux. The cache directory must still belong to the daemon
user, must not be group- or world-writable, and must have no symlinks in its path.
If the log says warm peer cache I/O failed, check those permissions and that no
other daemon is using the same directory. Streaming continues without durable hints.
A cold start has three stages:
- Resolving the content id through the catalog.
- Discovering peers through trackers and the DHT, then connecting.
- Prebuffering: collecting media before the first byte goes out, up to 30 seconds of media or 15 seconds after the first byte, whichever comes first. If the peers hold less history than that, playback starts as soon as all of it has arrived. HLS also waits for six segments.
20–60 seconds in total is normal with the defaults. To start faster, at the cost of more stutter on weak swarms:
export OUTPACE_PREBUFFER_MS=5000 # direct TS and HLS
export OUTPACE_HLS_STARTUP_SEGMENTS=2 # HLSThen start (or restart) Outpace from the same shell. With docker run, pass each setting
as -e NAME=value; with Compose, see Deployment.
The logs show which stage is slow:
[ace] discovery stage=resolved resolve_ms=...
[ace] discovery stage=first-candidates after_resolution_ms=... count=...
[ace] discovery stage=tcp-connected
[ace] discovery stage=first-source-output
[prebuffer] startup buffer released: reason=TargetDuration duration_ms=... queued_bytes=...
The reason on the [prebuffer] line tells you why playback started:
| Reason | Meaning |
|---|---|
TargetDuration |
The full target was reached. |
Deadline |
The 15-second limit expired; playback started with what was there. |
BacklogExhausted |
Every piece the peers hold up to the live edge has arrived, so playback started with that shorter backlog instead of waiting for the target. |
ByteLimit |
The 128 MiB cap was hit. |
EndOfStream |
The source ended during startup. |
Disabled |
Prebuffering is off. |
The playlist request waited OUTPACE_HLS_STARTUP_TIMEOUT_MS (45 seconds) and fewer than
OUTPACE_HLS_STARTUP_SEGMENTS segments were ready. The response carries Retry-After: 1, and
most players retry on their own.
- If it eventually plays, the stream is just slow to start. Lower the startup segment count or raise the timeout.
- If it never plays, check the stream's
/status.peers: 0means a discovery problem;bitratenear 0 means the peers aren't delivering. - A
503that never goes away, after playback had worked, can mean audio normalisation failed. Checknormalizationin/status. Stop the stream and start it again.
Check the stream's /status while it stalls:
-
peersdropping, orrecovery.upstream_reconnectsandrecovery.stale_teardownsclimbing: the swarm is losing peers. Outpace reconnects on its own. -
recovery.skipped_evicted_gapsclimbing: peers no longer had the pieces Outpace needed, so it skipped ahead. That shows up as a jump or glitch in the picture. -
bitratefar belowmetadata.bitrate: not enough upload capacity in the swarm.
Matching log lines:
[ace] re-requesting 3 piece(s) outstanding > 1.5s (from ...)
[ace] upstream pool stale ...
[ace] rebuilding upstream pool: reason=PoolStale ...
[ace] next needed piece evicted from all upstream windows; skipping ahead to ...
[ace] cursor fell too far behind live edge ...; re-syncing forward to piece ...
What helps:
- A larger startup buffer (the default 30 seconds is already generous) gives more slack.
- Being reachable (an open port 8621) lets more peers connect to you.
- Avoid VPNs.
- Leave the live recovery settings alone. Raising
OUTPACE_REQUEST_TIMEOUT_MSmakes stalls longer, not shorter.
Also check the player: a client that reads slower than real time eventually falls behind the server's window and gets a discontinuity.
The status route shows a phase while a stream starts and,
when the start fails, an error.code. Native playback and VOD routes return the same JSON
error in their response body:
curl "http://127.0.0.1:6878/streams/ace/${CONTENT_ID:?set a content id}/status"| What you see | What it means |
|---|---|
phase stays resolving
|
The descriptor lookup is slow. Check outbound network access to the catalog. |
phase stays connecting
|
No peer connected yet. See No peers, or discovery fails. |
phase stays buffering
|
Peers are connected but media isn't arriving. See Slow startup. |
no_peers |
Nobody is sharing the stream right now. Try a stream you know is live. |
network |
The catalog couldn't be reached. Check VPNs, WARP and firewalls. |
unresolvable |
The id has no verified descriptor; message says what to try (often the cid: content id). |
protected |
Encrypted content. Outpace doesn't play it. |
capacity |
The session cap, the catalog resolver or audio conversion is at capacity. Retry shortly; see Too many streams. |
no_space |
VOD only, with the disk cache: the file won't fit on the cache disk (507), and message gives both sizes. Free space on the disk holding OUTPACE_CACHE_DIR, move it to a bigger disk, lower OUTPACE_SEED_STORE_BYTES or OUTPACE_VOD_DISK_RESERVE_BYTES, or use the memory cache. See VOD free-space check. |
internal |
Something else failed. Check the log. |
status shows peers: 0 for a long time, phase stays connecting, or the start fails
with no_peers:
- Is the stream alive? Try another one. Dead channels never find peers.
- Outbound UDP must work for the DHT and trackers (replies to outbound UDP must come back). Some firewalls and VPNs block this.
- Outbound TCP to arbitrary ports must work to reach peers.
-
Peer-to-peer blocked on this network? If the same stream plays from another network,
route Outpace's own connections through a SOCKS5 proxy with
OUTPACE_PROXYandOUTPACE_PROXY_MODE=onorfallback. See Outbound Proxy. -
Proxy already on? Check
network_pathin the stream's/status, and look for[proxy] proxy unusableorproxy does not support UDP ASSOCIATEin the log. WithoutUDP ASSOCIATEsupport and with the DHT off, a proxied start has fewer ways to find peers; bootstrap peers (OUTPACE_ACE_PEERS) help. -
422with codeunresolvable: the id couldn't be resolved. Forih:infohashes, Outpace needs a verified descriptor; try the content id instead. - Compat
502 stream start failed: resolution or discovery failed. Compat422 stream metadata unavailable: no descriptor was found for an infohash or magnet. Neither proves the content is gone for good. - A content id of a broadcast made by another Outpace daemon only resolves with
OUTPACE_BEP9_CONTENT_ID_FALLBACK=1. See Broadcasting.
[dht] walk done: ... peers=N tells you how many peers the DHT found.
The log keeps saying:
[reachability] externally reachable: no (0 inbound peer(s) ...)
[reachability] HINT: after 10 minutes, no inbound peers or yourip observations; check advertised peer TCP port 8621 ...
Work through these:
- Is inbound serving on (
OUTPACE_ENABLE_INBOUNDnot0)? Did you publish8621:8621/tcp? - Does the router forward TCP 8621 to this machine's port 8621, with the same port on both sides?
- Does the host firewall allow inbound TCP 8621?
- Test from outside your network:
timeout 8 bash -c 'echo > /dev/tcp/<public-ip>/8621' && echo open. - A
WARNING ... likely double-NAT / CGNATline means your ISP's NAT is in the way. - VPN or WARP? See NAT and Port Mapping.
- Outbound proxy active? Nothing is advertised then; see NAT and Port Mapping.
Playback doesn't need inbound peers. You can also run download-only
(OUTPACE_ENABLE_INBOUND=0).
503 with Retry-After: 1 when opening a new stream, and
[manager] session capacity reached in the log: you hit OUTPACE_MAX_SESSIONS. Raise or unset
it, or stop unused streams. A slot frees up only after the stream's cleanup has finished.
Shutdown ends viewer connections first, then gives broadcasts up to 5 seconds to clean up. A stop that still takes long usually means a stuck filesystem operation; the log names the step that gave up. See Deployment.
Each line looks like HH:MM:SS.mmm [tag] message, where the time is UTC. The tag says which part
of Outpace logged it:
| Tag | Area |
|---|---|
[ace] |
Resolving content, discovering and managing peers, downloading a stream. Most playback lines. |
[ace-compat] |
The AceStream-compatible API. playback start failed: error=<category> status=<code>. |
[prebuffer] |
Startup buffer release, with reason and duration. |
[mpegts] |
Repairing a damaged or misaligned TS byte stream (transport resync). Occasional lines are harmless. |
[hls] |
HLS packaging, for example a segment ceiling too small. |
[manager] |
Stream lifecycle: capacity reached, idle cleanup. |
[session] |
Problems cleaning up one source. |
[dht] |
DHT peer search results. |
[reachability] |
Whether inbound peers can reach you, every two minutes. |
[portmap] |
UPnP/NAT-PMP mapping, renewal and removal. |
[dlna] |
Casting: discovery results, skipped devices, play and stop on a renderer. |
[seed], [seed-listener]
|
Inbound seeding: accepted connections, cleanup of idle seeding data. |
[seed-session] |
Per-message seeding detail. Only shown with OUTPACE_SEED_DEBUG set. |
[cache] |
Disk cache errors. |
[vod] |
VOD failures by code, for example start refused: code=no_space required=<bytes> available=<bytes> or download stopped at piece <n>: code=no_space. |
[broadcast] |
Broadcasts: reloads, tracker warnings, cleanup. |
[rtmp], [srt]
|
Ingest listeners. |
[support] |
Support sources. |
[runtime] |
Daemon start and shutdown. |
Lines without a tag are messages for the person at the terminal, such as
outpace: listening on ... at startup.
OUTPACE_SEED_DEBUG=1 adds a log line for every seeding message. Turn it on only briefly while
debugging inbound peers.
Open a bug report. The form asks for everything below. For slow startup, stutter, CPU or memory problems, use the performance form instead. A report should include:
-
outpace --version, and whether you use a release,edge(with itssha-tag) or your own build; - the platform (OS, architecture; container or bare metal);
- the non-default
OUTPACE_*settings you use; - what you did, what you expected and what happened: the HTTP status, the player's error, and
a
/statussnapshot; - whether it happens with other live streams, and whether the same stream plays in another engine at the same time, if you can check;
- the stream's characteristics instead of its identity: live or VOD, bitrate, codecs if known, and the peer count;
- a log excerpt around the problem.
Don't include stream identifiers. Before you paste anything:
- Replace content ids and infohashes (40-character hex strings) with a placeholder such as
0123456789abcdef0123456789abcdef01234567. They appear in URLs,/streamsoutput,/statusand some[ace]log lines. Magnet links carry the infohash too, sometimes as a 32-character base32 value. - Remove stream and channel names (the
titleandIcy-Namevalues). - Remove broadcast source URLs and any tokens, SRT passphrases, your public IP and peer IP addresses (IPv4 and IPv6).
- Don't attach captures or recordings of the media.
If the specific stream turns out to matter, the maintainer will arrange a private channel. Don't post it in the issue.
To mask hex ids and IPv4 addresses in a log, and the id and title in a /status snapshot:
sed -E 's/[0-9a-fA-F]{40}/<id>/g; s/([0-9]{1,3}\.){3}[0-9]{1,3}/<ip>/g' outpace.log > outpace-redacted.log
curl -s "http://127.0.0.1:6878/streams/ace/${CONTENT_ID:?set a content id}/status" \
| jq '.id = "<id>" | .metadata.title = "<title>"'Check the result by eye before you paste it: these commands don't catch stream names in log lines, IPv6 addresses or base32 magnet links.
Ask in Discussions. See the FAQ for common questions: do you need the official engine, Docker, VLC, Jellyfin and Dispatcharr, broadcasting, and the differences from the official engine.
This wiki is generated from docs/wiki/ in the main repository. To fix or improve a page, open a pull request there; the wiki is republished automatically when it merges, and edits made in the wiki web UI are overwritten.
Start
Watching
Publishing and peers
- Broadcasting
- Seeding and Peers
- Engine Camouflage
- NAT and Port Mapping
- Private Peer Mode
- Outbound Proxy
Running it
- Deployment
- Routers and Small Devices
- Migrating from AceStream Engine
- Support Sources and Operations
- Troubleshooting
- Releases and Versions
Success stories