A Restreamer Docker container that repeatedly restarts is reporting a symptom, not a diagnosis. Capture its state, recent Docker output and Restreamer logs before changing settings; together, those records can show whether to investigate the runtime, application, configuration, image version or stream input.
This guide follows that evidence from collection through a controlled retest. Do not treat --restart=always as a repair: it tells Docker to restart a container after a crash or device reboot, but it does not explain why the process exited.
Capture the restart symptom before changing anything
Start by recording what is happening and when. Note the container name or ID, the time you noticed the loop, whether the stream was active, and what changed recently: a new image pull, edited Compose file, host reboot, new input or hardware change. If the exact start time is unclear, record when you begin observing rather than guessing.
Avoid immediately removing and recreating the container, pulling a newer image or changing several environment values. Those actions can replace useful evidence or make it harder to tell which change mattered. If the stream is currently unavailable, preserve what you can first, then decide whether service restoration or a longer diagnosis takes priority for your channel.
Use Docker's current CLI documentation to confirm command syntax for your installed version and shell. The examples below are common Docker CLI patterns; replace restreamer with the actual container name or ID. Save output in a dated text file outside the container so it remains available if the container is replaced. Be careful when sharing it: environment details or log lines may expose stream URLs, credentials or other private configuration.
A simple evidence note can include the image reference, container ID, restart policy, timestamps, exit information, recent output and event history. Add the relevant Compose file or docker run command, with secrets redacted. This gives you a before-and-after record and makes it possible to return to the same deployment if a test does not help.
Inspect container state and restart count
Ask Docker what it currently knows about the container before interpreting application logs. The docker ps -a listing can show whether the container is running, restarting or exited. Then inspect its state and restart count:
docker ps -a --filter name=restreamer
docker inspect restreamer
The inspection output is large. For a short summary on installations that support Go-template formatting, try:
docker inspect --format '{{.State.Status}} {{.State.ExitCode}} {{.State.Error}} {{.State.StartedAt}} {{.State.FinishedAt}} restart-count={{.RestartCount}}' restreamer
Check the result against the full inspection output if the summary is empty or behaves differently on your Docker version. Record the state, exit code, any reported error, start and finish times, and restart count. A count that increases while you watch confirms repeated restarts; one number by itself does not tell you the cause. An exit code is a clue to compare with logs and events, not proof of a particular failure.
Also inspect the restart policy and the image identity. A policy such as always can make a short-lived failure look like a persistent loop because Docker keeps bringing the process back. It is useful for recovery after a transient exit or host reboot, but it can also cause repeated attempts before you have found the reason. Record the policy instead of switching it off as a first response.
If the container appears to be restarting too quickly for you to inspect interactively, do not rely on attaching to it at just the right moment. Docker retains state and recent output independently of whether the process is currently alive. Preserve the output and inspect again after a short observation period, noting whether the count and timestamps move.
Read Docker’s recent output and events
Read the container's recent stdout and stderr with timestamps:
docker logs --timestamps --tail 300 restreamer
The --tail value limits the displayed lines; it is a collection choice, not a Restreamer setting or a universal amount of history. If the exit message may be older, increase it or save the full output. You can also follow new lines while observing a restart, but save the preceding output first. Look for the final messages before exit, repeated messages across starts, and whether the output stops abruptly. Do not assume the last visible line is necessarily the cause: a process can fail after logging something else, and Docker may not capture every application detail.
Next, compare output with Docker events around the recorded time. The exact filtering options vary by CLI version, so check the Docker CLI documentation before relying on a command. Events can help establish a sequence, such as a container die event followed by a restart, or a stop initiated by an operator. They provide runtime context, not an application-level explanation.
Ask practical questions of the timeline. Did the container exit before the stream input began, or only after a source or process was added? Did the host reboot at the same time? Did a stop event precede the restart? Are the output lines identical on each attempt, or does one attempt progress further? A consistent sequence narrows what to inspect next; it does not justify changing a setting until you can connect the proposed change to evidence.
Keep the original logs intact when testing. If you need to share them in an issue, remove stream keys, passwords, private URLs and personal information, but retain timestamps and the surrounding lines that make the sequence intelligible.
Find and review Restreamer logs
Docker output may not contain the detail you need from Restreamer's system log or the FFmpeg process. Restreamer's logging guide describes the logging controls in its interface. When the container stays up long enough to open the interface, inspect the system log and process details around the same timestamps as the Docker exit. Look for an explicit error, the named process, and whether the message repeats before every restart.
If the interface is unavailable during the loop, use whatever output is available from Docker and consider a brief observation window after a start, rather than repeatedly changing the deployment. Restreamer's troubleshooting sequence recommends trying a virtual source and then checking process details and logs. A virtual-source test can help distinguish an issue that occurs even without your normal media input from one that appears only with that source or workload. It cannot, by itself, prove the exact cause.
Logging levels documented by datarhei include silent, error, warn, info and debug; the environment variable reference lists info as the default for CORE_LOG_LEVEL. That reference also lists defaults for retained system and FFmpeg log lines. These are version-sensitive details, so check the environment-variable reference against the release actually deployed before changing them. More verbose logging may expose useful context, but it can produce more output; change the level only when the current logs lack the detail required for a defined test.
Do not increase several logging controls and alter stream settings in the same step. First preserve the current logs and configuration. If a specific error is truncated or absent, make one logging change consistent with the deployed version, observe one reproduction, and compare the new record. Restore the previous value if extra logging adds no useful evidence or creates a different operational problem.
For a YouTube channel, keep this container diagnosis separate from questions about YouTube ingest or channel access. If you are also checking the path from a recorded source to YouTube, the practical walkthrough of using an OBS stream key with a recorded video playlist covers that adjacent setup; it does not substitute for Restreamer’s own process logs.
Compare configuration, persistent paths and image version
Once the time and logs are captured, compare the live container with the deployment definition that created it. Restreamer's Linux installation guide maps host directories to /core/config and /core/data so configuration state and internal filesystem data can persist outside the container. Use docker inspect to review mounts and compare them with the volumes entries in your Compose file or the -v options from the run command.
Check both ends of each mapping: the host path you intended, and the path inside the container. A mapping to an unexpected directory, a missing mapping, or a changed host directory is a reason to investigate storage and configuration. It is not proof that the restart loop comes from a mount. Do not delete, empty or replace those paths as a generic reset; first make a backup and establish what data they contain.
Compare the effective environment values and command-line options with your saved configuration. Docker command-line environment values can override values from a .env file, according to the Restreamer environment-variable reference. That makes the live container inspection more useful than relying on a .env file alone. Redact secrets before saving or sharing the output.
Record the exact image name and tag, not just “latest” or “Restreamer”. Note whether it is an official datarhei image or a custom build, and whether the tag or release changed before the first observed failure. Restreamer recommends official Docker images to reduce differences in dependencies and operating systems. That recommendation helps limit variables; it does not establish that an official image will resolve a particular reader's failure.
Version changes deserve particular care. Restreamer's migration notes describe a change to FFmpeg 5.1.2 in v2.4 and a limited downgrade procedure for issues related to that version break. This does not show that your loop is a migration problem. If you are considering a rollback, verify the applicable release history and instructions, preserve configuration first, and account for the migration page's warning that processes created with the newer version cannot be restored by that procedure. Do not pull a different tag as an unrecorded experiment.
If you use systemd or another supervisor around Docker, note that too. A host-level unit may be starting or replacing a container in addition to Docker's own restart policy. The systemd always-on stream guide explains why the supervisor layer belongs in the operational picture, though its service examples are not a diagnosis of this Restreamer container.
Check host-level evidence and the input path
A container can exit amid a host event, so compare timestamps with the machine's own records. Check the host's system journal or operating-system logs for messages at the same time: reboot, shutdown, storage warnings, service restarts, or runtime errors. Use the logging tools and retention policy appropriate to your Linux distribution. If the host itself is unstable or has lost records, mark that gap rather than treating the absence of a message as evidence that nothing happened.
Review resource and device evidence without assuming a particular shortage. If host monitoring or kernel logs show a memory, disk, CPU or device problem at the exit time, preserve the actual line and its timestamp. If they do not, do not label resource exhaustion the cause merely because the container restarts. Hardware encoding, architecture compatibility and permissions are also hypotheses to test against the image, host and process evidence, not default explanations.
Compare the normal workload with a virtual source, following Restreamer's basic troubleshooting guidance. If the virtual source runs while a particular input fails, inspect the source format, process details and any hardware-specific options that differ. If the container still exits without the normal input, focus on the common runtime, application, configuration and host evidence. Either result narrows the investigation, but neither warrants a broad change unrelated to the observed difference.
For channels that depend on a separate machine or storage device, map the full path: where the media is stored, how Restreamer reads it, and what the host reports when the stream is attempted. The article on buffering from a home NAS addresses a neighbouring delivery problem; buffering and a container restart are different symptoms, so use it only if your evidence points to the media or network path.
Apply one evidence-based change and retest
Choose a change only after you can state the evidence it addresses. For example, a confirmed mismatch between the intended and live mount justifies correcting that mapping; a reproducible failure tied to one input makes a virtual-source comparison useful; a relevant documented migration issue calls for version-specific review. If the records do not distinguish between possibilities, collect more evidence instead of trying several fixes at once.
Before editing, save the deployment file, image tag, environment values and a copy of the relevant logs. Back up persistent configuration and data before any action that could replace or migrate them. Change one variable, recreate or restart only as required by that change, then capture the same state, recent output, events and Restreamer logs again. Compare the timestamps and messages with the original run, not with memory.
A successful start is not yet proof that the underlying issue is resolved. Observe whether the container remains in its intended state under the same source and workload, and whether the process logs progress as expected. If the failure returns, record the new evidence and revert the single change where appropriate. Avoid a chain of speculative edits that leaves you unsure which condition changed.
If the virtual-source test and log review do not resolve the problem, Restreamer's troubleshooting page recommends opening a GitHub issue with a detailed description and process report. Include the exact image tag, host architecture, relevant deployment configuration with secrets removed, state and restart history, timestamped Docker output, application/process logs, and the result of the virtual-source test. A concise timeline is more useful than a large unlabelled paste.
A repeated container restart can also become a reason to reconsider where the broadcast workload runs, but that is a deployment choice rather than a diagnosis. If your actual goal is to loop a fixed video on YouTube without keeping a computer on, StreamNeo removes the need to recover a local Restreamer container by turning an uploaded file into an always-on YouTube broadcast. Keep that separate from any investigation where you need Restreamer's inputs, process controls or other capabilities.
Before committing, compare the operating options on the pricing page. When the file and channel are ready, start free — 24-hour trial, no card.
FAQ
Does --restart=always fix a Restreamer restart loop?
No. It is a Docker restart policy that starts the container again after a crash or device reboot, as documented in Restreamer's Linux installation instructions. It can keep a service returning, but you still need the state, output, application logs and host evidence to identify why it exited.
Which logs should I collect first?
Start with timestamped Docker output, the container's state and restart count, and events around the exit. Then compare those with Restreamer's system and FFmpeg process details, plus host records at the same time. Preserve the original material before changing logging or deployment settings.
Should I downgrade after a Restreamer version change?
Not on the basis of a restart loop alone. Check the exact deployed version and migration history, then follow the version-specific migration guidance only if the evidence fits; back up persistent configuration and data first. The documented downgrade procedure has limitations, including for processes created with the newer version.
What if the container exits before I can open the Restreamer interface?
Save Docker state and recent output, then compare host and Docker event timestamps. Check whether a virtual-source test is possible during a brief start, and preserve any process details you can access. If those records do not explain the exit, prepare a redacted process report for the official troubleshooting route rather than guessing at a fix.