Troubleshooting
Common failures in the approximate order they occur, with the distinguishing symptom for each.
Initial checks#
Three checks resolve most problems. Perform them in this order before consulting the sections below.
Connected is not sufficient; the worker must be approved. A worker in pending approval sends heartbeats normally and never receives a chunk. This is the most common cause of a fleet that appears to do nothing.
The master opens the file, not the browser and not the worker. A path that exists on the submitting machine is not necessarily a path the master can read.
The queue records that a job failed. The activity log records why. Consult it before changing any settings.
Workers not appearing#
| Symptom | Cause | Fix |
|---|---|---|
| Worker runs but never appears on the master | 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 | The worker is pointed at the web port instead of the worker port, or a firewall is blocking the connection. | Use 7444, not 7443; run master.exe firewall-install on Windows |
| Registration rejected | Enrollment token missing or does not match. | Set the identical value in the master's and the worker's settings |
| Worker settings appear to be ignored | The settings are in the wrong file. Master settings use TRNSCODE_; worker settings use TRNSCODE_WORKER_. | Move them to the correct file and restart that service |
Each worker serves a local health endpoint on its own machine. If the endpoint does not answer, the process is not running; that is a process problem, not 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 skipped by design. 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. When every cell is solid but the job remains open, joining, muxing and verification are running on the master. This is expected, and additional workers do not shorten it.
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 | A preset incompatible with this source, in most cases. Check the source-rule warnings on the review screen. |
| Fails on one worker, succeeds elsewhere | A condition on that machine: a full disk, a failed accelerator, or an FFmpeg build 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; it was overwritten, still transferring, or being synced. |
Output problems#
- Nothing in the output directory.The master writes the finished file, so the master's filesystem and permissions apply, not the worker's.
- Output looks soft. An upscale is the usual cause. A 1080p source in a 4K preset produces a genuine 4K file with no added detail, and it passes verification because it matches what the preset specified.
- Watch folder produced a truncated file. The file 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, inspect the last few seconds specifically. Truncation is the failure most likely to pass a brief visual check; the duration verification exists to catch it.
Slower than expected#
Distribution does not benefit every job equally. In approximate order of frequency:
- The tail chunk. The job finishes when its slowest chunk does. One much slower machine sets the time regardless of how many fast machines are added.
- The source is too short. Coordination overhead can exceed the saving on short clips in inexpensive codecs.
- Transfer, without shared storage. Every chunk crosses the network twice. On high-bitrate sources that can exceed the encode time.
- A wireless worker. Where the non-wired override is enabled, reduced throughput is the expected cost.
- Assembly. Assembly runs on the master and is not reduced by adding workers.
Log files#
The activity log explains most job failures, but a problem that predates any job — a service that will not start, a configuration rejected at boot — leaves no activity entry. For those, and for anything a support request needs, each service writes a durable log file.
| Service | File |
|---|---|
| Master | <state-dir>/master.log |
| Worker | <state-dir>/worker.log |
Each file carries every log line the service emits, as JSON, one per line, and it is written even when the console window is hidden. Secrets are redacted from it, so it is safe to attach to a support request — and it is the single most useful thing to include. The default location is a .trnscode-master (or .trnscode-worker) directory beside the executable; override the master's path with TRNSCODE_LOG_FILE, documented in Configuration.
Administrator access recovery#
If the administrator password is lost, stop the master and reset the password from the bundle folder. Job history is unaffected.
$ master reset-admin-password "a new password"Take a backup before any recovery attempt. 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.