Troubleshooting
The failures people actually hit, roughly in the order they hit them, with the distinguishing symptom for each.
Start here#
Three questions resolve most problems before you read any further. Ask them in this order.
Not connected — approved. A worker sitting in pending approval heartbeats happily and never receives a chunk. This is the single most common cause of "nothing is happening".
The master opens the file, not your browser and not the worker. A path that exists on your laptop is not a path the master has.
The queue tells you a job failed. The activity log tells you why. Go there before guessing.
Workers not appearing#
| Symptom | Cause | Fix |
|---|---|---|
| Worker runs, never shows on the master at all | Refused for being on a non-wired link. Wi-Fi, cellular and sub-gigabit ethernet are rejected by default. | Use ethernet, or set the override — see Allowing non-wired workers |
| Worker cannot find the master | Discovery does not cross subnets and is blocked on many managed networks. | Set TRNSCODE_WORKER_MASTER_GRPC_TARGETto the master's address |
| Connection refused | Pointed at the web port instead of the worker port, or a firewall is blocking it. | Use 50051, not 7443; run master.exe firewall-install on Windows |
| Registration rejected | Enrollment token missing or does not match. | Same value in the master's and the worker's settings, exactly |
| Worker settings appear to be ignored | Put in the wrong file. Master settings are TRNSCODE_; worker settings are TRNSCODE_WORKER_. | Move them to the right file and restart that service |
Each worker serves a local health endpoint on the machine itself. If it does not answer, the process is not running — that is a different problem from a networking one.
Workers idle while jobs queue#
- Pending approval. Approve it on the Workers page.
- Missing the capability.The scheduler treats a worker's reported codecs as a hard constraint. A worker that cannot produce what the preset requires is correctly skipped — compare its capabilities against the preset.
- Not enough chunks. A short source does not divide into enough work to occupy every machine. At twelve seconds per chunk, a two-minute clip is about ten units of work.
- The job is assembling. Every cell solid but the job still open means joining, muxing and verification are running on the master. That is expected and more workers do not speed it up.
Jobs failing#
| Symptom | Likely cause |
|---|---|
| Probe fails at submission | The master cannot read the path, or the file is not media it recognises. |
| Fails immediately on every worker | Usually the preset against this source. Check the source-rule warnings on the review screen. |
| Fails on one worker, succeeds elsewhere | That machine — full disk, a broken accelerator, or an FFmpeg that differs from the rest of the fleet. |
| Fails at the end, after all chunks completed | Assembly or verification. The duration did not match within tolerance, or audio was expected and missing. |
| Source fixity reported a change | The source file changed while the job ran — overwritten, still transferring, or synced. |
Output problems#
- Nothing in the output directory.The master writes the finished file. Its filesystem and permissions are what matter, not the worker's.
- Output looks soft. Probably an upscale. A 1080p source in a 4K preset produces a real 4K file with no added detail, and it passes verification because it is exactly what the preset asked for.
- Watch folder produced a truncated file. It was picked up mid-copy. Use a sentinel marker instead of relying on size-stability — see Watch folders.
- Watch folder encoded its own output. The output directory is inside the watched directory and matches the pattern. Separate them.
When validating output, look at the last few seconds specifically. Truncation is the failure that survives a casual check, and it is what the duration verification exists to catch.
Slower than expected#
Distribution does not help every job equally. In rough order of how often each is the answer:
- The tail chunk. The job finishes when its slowest chunk does. One much slower machine sets the time regardless of how many fast ones you add.
- The source is too short. Coordination overhead can exceed the saving on brief clips in cheap codecs.
- Transfer, without shared storage. Every chunk crosses the network twice. On high-bitrate sources that can exceed the encode time.
- A wireless worker. If you enabled the override, this is the likely cost of it.
- Assembly. Master-side, and not reduced by adding workers.
Getting back in#
Lost the administrator password: stop the master and reset it from the bundle folder. Job history is untouched.
$ master reset-admin-password "a new password"Take a backup first. master backup --out … is safe while the service is running; copying the database file with a file manager is not. Restoring replaces everything created since the backup was taken.