FFmpeg’s “Could not write header” message is a generic output-initialisation failure; by itself, it does not identify the cause. Start with the first specific error above it in the log, then check the output format, mapped streams, codecs and destination settings.
Without your full command and log, nobody can responsibly say which setting is wrong or offer a confirmed fix. The checks below help you narrow it down without treating a plausible example as a diagnosis.
What “Could not write header” tells you
FFmpeg writes a header to an output before it starts sending the media packets. The header describes the output container and the streams it will carry. To write it, FFmpeg needs enough information about the selected format, mapped audio and video streams, their codecs and, for a network destination, the output connection.
If this initialisation step fails, FFmpeg may end with a message such as Could not write header for output file #0 (incorrect codec parameters ?): Invalid argument. That wording is a broad failure report, not a reliable explanation of which parameter is invalid. The more useful clue is usually another line immediately before it, where a muxer, codec, stream or network layer reports what it rejected.
A failure at header-writing time is also different from a stream that starts and then drops frames or disconnects. If the broadcast already began, capture the log around the later failure instead of assuming the initialisation checks explain it. For a running broadcast, this guide to logging RTMP reconnects in FFmpeg covers a different part of the problem.
Do not infer that YouTube is down from this message. It does not establish that the service is unavailable, and it does not tell you whether the issue lies in the command, your input media, the output muxer or the destination settings. The root cause remains unknown until the command and complete log can be examined.
Find the first specific error in the log
Capture the entire FFmpeg output from the beginning of the run through the failure. Searching only for the final line discards the context that makes it useful. Look upwards from “Could not write header” for the first message that names an output stream, codec, format, protocol or rejected option. Preserve that line exactly, including its stream number and error text.
The final line may say Invalid argument, but that phrase alone does not identify which argument is invalid. One line earlier, FFmpeg may say that a codec is not supported by the selected output format. Or the first specific message may concern an option that cannot be applied to the output, a stream that was not mapped as expected, or a failed connection. Those possibilities call for different checks, so do not skip directly to a command copied from a forum.
An old FFmpeg-user mailing-list report illustrates the pattern: a message about a codec that the FLV output could not accept appears before the generic header failure. That report is useful as an example of where to look, not proof that another user has the same problem. Read the archived FFmpeg report in that light. The command, FFmpeg build and media in that case are not a substitute for yours.
For a readable capture, save standard error as well as standard output; FFmpeg commonly prints diagnostic messages to standard error. Do not trim the initial option and input information, the stream mapping summary or the first failure. If you are sharing the log publicly, remove your stream key and any other private credentials first. Keep the remaining wording and ordering unchanged so another person can follow the failure sequence.
Check the output muxer
A muxer writes streams into a particular output format. The container or protocol you intend to use must be compatible with the streams and codecs FFmpeg is being asked to send. A command that works for a file with one format does not automatically make that format appropriate for a YouTube ingest connection.
Inspect the output options near the end of your full command. Note whether the format is selected explicitly, whether FFmpeg is expected to infer it from a filename or URL, and whether the command uses a direct RTMP/RTMPS output or an intermediate such as tee or FIFO. In a complex command, look at options in their position relative to the output they affect; FFmpeg options can be scoped by where they appear.
FFmpeg’s format documentation describes available muxers and includes an RTMP example that selects video and audio streams and writes FLV. It is a reference for understanding the format and mapping choices, not a recipe to paste into an unknown setup. Available formats and options can vary by FFmpeg version and build, so confirm what your own binary supports.
An incompatible-codec example can help you understand the diagnostic pattern: if the log explicitly says that the selected muxer rejects a codec, investigate the codec and output format together. It does not justify changing codecs when your log says something else. Avoid adding a guessed format flag or replacing the command wholesale until you know which output and streams it actually describes.
Inspect mapped streams and codecs
The input file can contain multiple video, audio, subtitle or data streams. FFmpeg’s mapping summary tells you which of them the command selected for output. Read that summary alongside the command’s -map, codec-copy or encoder options. A stream present in the input is not necessarily intended for the output, and copying all streams is not automatically valid for the chosen muxer.
Check whether the output has the audio and video streams you expect, whether each selected stream has a codec, and whether the output options act on the intended stream. If a command uses -c copy, FFmpeg is not transcoding the selected stream to another codec; the existing codec must be acceptable to the output format and destination. If it encodes instead, check which encoder is selected and whether the input can be converted as requested. Do not assume a codec change is needed unless the log or stream information supports that conclusion.
For YouTube Live, the current encoder settings guidance lists RTMP/RTMPS ingest, H.264, H.265/HEVC or AV1 video, and AAC or MP3 audio. These are useful checks against the selected output streams; they do not diagnose an FFmpeg header error by themselves. If the log points to an unsupported codec or stream, compare the actual output stream with the current guidance and the muxer’s capabilities before changing anything.
Use FFmpeg’s input information or a probe of the file to establish what it contains. Record stream type, codec, dimensions, frame rate and audio details where present. Then compare those facts with the streams the command maps and with the encoder options. If you have a playlist or a long-running loop, check whether every item has compatible streams; a later file with a different layout may produce a separate failure after an otherwise valid start. Guidance on batch-converting files for YouTube Live can help you think about file consistency, but it does not establish the cause of this error.
Verify destination settings
Once the local output format and stream choices make sense, verify the destination. In YouTube Live Control Room, check the ingest URL and the current stream key for the intended broadcast. A mistyped or stale destination can cause a network-side error, though the final header message alone does not show that this is what happened.
YouTube recommends RTMPS, its encrypted extension to RTMP. If you use RTMPS, confirm that your FFmpeg build and output method support it, and use the RTMPS URL shown for your stream in Live Control Room. YouTube’s RTMPS guidance explains the protocol and destination details. Do not replace a URL with one found in an old example; use the value shown for your own stream.
Check the live dashboard for its own error or stream-health feedback. YouTube’s live streaming error guidance and stream settings page are the relevant official references for destination and dashboard checks. Dashboard feedback may help distinguish an ingest problem from a local command problem, but it does not remove the need to read FFmpeg’s first specific error.
YouTube’s recommended encoder settings are a separate check from muxer initialisation. Its guidance calls for constant bitrate encoding and recommends a two-second keyframe frequency, not exceeding four seconds. Match any bitrate comparison to the exact codec, resolution and frame rate row in the current table. For example, YouTube lists H.264 at 1080p60 with a 6 Mbps minimum and 17 Mbps recommended; H.264 at 1080p30 has a 5 Mbps minimum and 14 Mbps recommended. Those figures are ingest recommendations, not a way to identify the cause of “Could not write header”.
| Check | What to compare | What it can tell you |
|---|---|---|
| Output format | The selected muxer and intended destination | Whether the format is appropriate for the output path and streams |
| Stream mapping | Input streams, mapping summary and output options | Whether the expected audio and video are selected |
| Codecs | Actual or encoded output codecs against muxer and YouTube guidance | Whether a specific compatibility warning has a plausible target |
| Ingest settings | Live Control Room URL/key and RTMP or RTMPS support | Whether destination details or protocol support need checking |
| Encoder targets | The YouTube row for codec, resolution and frame rate | Whether the live output settings align with current guidance, independently of the header failure |
Work through the table in order rather than changing several settings at once. Make a note of the original command and the exact result of each controlled change. If a change affects the first specific error, that is more useful evidence than simply observing that the final line disappeared after multiple edits.
Compare the log with the full command
The command and log answer different questions. The command tells you what you asked FFmpeg to do; the log tells you what it recognised, mapped and rejected. Read them together. A line about output file #0 should be matched to the corresponding output in the command, particularly if the command has more than one output or uses a filter, tee or FIFO.
Check option order and scope rather than looking for a familiar flag in isolation. Confirm where each input begins, which options precede each output, and whether a codec, format or bitrate option is attached to the intended output. A command pasted across several lines can be accidentally altered by shell quoting or line breaks, so share the exact command as executed, not a reconstruction from memory.
If you have changed the command during troubleshooting, retain both the original and revised versions, along with the log from each run. Change one relevant item at a time when possible. That keeps the result interpretable: if the failure moves or the first specific message changes, you can see which change coincided with it. If the same generic line remains but the preceding error changes, follow the new specific message rather than treating all failures as the same issue.
The same discipline matters for continuous broadcasts. Fixing an initialisation failure is not the same as planning for reconnects or ensuring a video loops without gaps. If your broader goal is a file-based 24/7 channel, see how to loop a video on YouTube Live without a VPS. Keeping the setup and the immediate error distinct makes it less likely that you will change a working part of the channel while diagnosing an unrelated failure.
What to include when asking for help
A useful report lets someone reproduce the reasoning, even if they cannot reproduce your exact stream. Include the complete FFmpeg command with the stream key replaced by [REDACTED], the full unabridged log from the start through the first failure, and the exact first specific error above “Could not write header”. State which output is intended for YouTube and whether it is direct RTMP/RTMPS or uses an intermediate method such as tee or FIFO.
Also include the FFmpeg version and build configuration, plus the input stream information for the file or source being sent. These details can show whether a format or encoder is available in your build and what streams the command is working with. Mention any relevant filters, maps, codec-copy settings, or changes you made immediately before the error appeared.
Do not share a stream key, password, private ingest URL or account credentials. Redact the secret but leave the surrounding option structure visible, so a reader can still tell where the destination is configured. If the log contains private information, remove that information without deleting the stream mapping or diagnostic lines.
Avoid posting only a screenshot of the last few lines, a guessed cause, or a claim that YouTube is unavailable. A concise, evidence-based summary is better: what you intended to send, what the first specific error says, and what you have already checked. Until those details are available, the exact cause is unresolved.
If the underlying difficulty is not diagnosing one command but keeping a prepared video live after a local computer is switched off, StreamNeo removes that particular need to leave your own machine running: you upload the file, provide the YouTube stream key and the broadcast runs as a 24/7 YouTube stream. That addresses a different operating constraint; it does not diagnose or repair an FFmpeg command that has already failed.
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 “Could not write header” mean YouTube is down?
No. The message reports that FFmpeg could not initialise the output header, but it does not establish why or where the failure occurred. Read the first specific error above it and check the destination separately in Live Control Room.
Is an incompatible codec the cause?
It is one possible cause only when your own log points to a codec or muxer incompatibility. An archived FFmpeg example shows that kind of diagnostic, but it cannot establish the cause in your command. Check the actual mapped streams and selected output format before changing codecs.
Should I copy a command from a forum to fix it?
Not without matching it to your inputs, FFmpeg build, output method and the first specific error in your log. A command that is appropriate for one file or muxer may be wrong for another. Share your exact command with the key redacted if you need help interpreting it.
Which YouTube bitrate should I use?
Use the current official table row for your codec, resolution and frame rate; its recommendations vary with those settings. The bitrate figures are encoder guidance, not a diagnosis of this header error. Check the output format, mapping and first specific log message independently.