How to Fix a Video Download That Gets Stuck or Stops Midway

A video download can start normally and then appear to freeze at 20%, 50%, 87%, or even 99%.

Sometimes the speed drops to zero for a short period and then comes back. Sometimes the download stays in the same state until the server eventually times it out. In other cases, the media has already been downloaded and the system is processing the file before it becomes available to save.

The important point is simple:

A download that appears stuck is not automatically a failed download.

Before restarting everything, identify which stage has actually stopped.

With MediaFetches, a download job can move through several distinct stages:

Queued → Preparing → Downloading → Processing → Ready

It can also end as Failed or Cancelled. The project exposes these states separately rather than treating every delay as the same problem.

That makes the first troubleshooting question more useful than "Why is my download broken?"

Ask:

What is the download doing right now?

First, Find Out Where the Download Is Actually Stuck

A frozen-looking progress bar can represent several completely different situations.

Waiting in the queue

If several downloads are already using the server, a new job may wait for an available download slot.

MediaFetches currently allows a default maximum of 3 simultaneous download processes. Additional jobs can wait in a bounded queue, with a default maximum of 20 queued jobs. These are server-capacity settings, not limits on your home internet connection.

The user-facing queue message is:

"Waiting for a free slot…"

If you see that state, changing Wi-Fi settings is unlikely to solve the immediate problem. The job is waiting for server capacity.

Preparing the download

After a slot becomes available, MediaFetches enters:

"Preparing your download…"

This is different from active byte transfer.

The server is handling the source and setting up the download process. A progress percentage may not behave like a normal transfer percentage during this stage.

Do not assume that an unchanged percentage means the network is broken.

Actively downloading

The downloading state is where MediaFetches receives progress information from the underlying download process.

The job can expose:

downloaded bytes total bytes percentage speed estimated remaining time

The interface therefore has more information than the percentage alone.

If the byte count and percentage are increasing, the download is not stuck even if the number has remained unchanged for a short period between updates.

Processing the media

After the source data has been downloaded, the job can enter:

"Processing media…"

This is particularly important when a user sees the transfer appear to reach the end and then thinks nothing is happening.

MediaFetches can use FFmpeg during the final processing stage. For video jobs that require separate video and audio streams to be combined, the project uses an MP4 merge/remux path with stream copying rather than video re-encoding.

The project also uses FFmpeg's +faststart option. FFmpeg documents faststart as a second pass that moves the MP4 index toward the beginning of the file, so this final stage is real work and does not necessarily finish at the exact moment the last source byte arrives.

Ready to save

Once server-side preparation and processing are complete, MediaFetches changes the job to:

"Ready to save"

At this point the server has a finished file.

This is a completely different situation from a source download that is stuck halfway.

Why a Download Can Stop Before It Finishes

There is no single explanation for a stalled transfer.

The interruption can happen anywhere along the path:

Your device → network → MediaFetches → source server

A problem on any one segment can affect the final result.

Temporary network interruptions

Wi-Fi and mobile connections are not perfectly continuous.

A device can briefly lose connectivity, switch networks, experience packet loss, or encounter a temporary routing problem.

Browsers can detect changes between online and offline states, but even an "online" indication does not prove that a particular website or server is reachable. MDN specifically notes that navigator.onLine is not a guarantee that a particular site is accessible.

That is why a download can temporarily stop while other parts of the internet still appear to work.

Wi-Fi instability

A weak or unstable Wi-Fi connection can interrupt a large transfer without making the device look completely offline.

Possible clues include:

other websites intermittently stop loading video streaming buffers the Wi-Fi icon changes repeatedly another large download also stops the problem disappears when the device moves closer to the router

If several unrelated downloads have the same problem, investigate the connection before blaming the source video.

Mobile-data changes

Mobile networks can change conditions while a large download is running.

Signal quality can vary, the device can move between network conditions, and background-data restrictions can affect applications.

Android's networking documentation emphasizes that connectivity can change over time and that applications need to account for changing network conditions rather than assuming a connection remains identical throughout a transfer.

Source-server interruptions

MediaFetches is not the original owner of the media source.

Its server has to retrieve the media from the source system first.

If that source becomes slow, temporarily unavailable, rate-limits the request, or stops delivering a particular media stream correctly, the MediaFetches job can be affected even when your own internet connection is working normally.

This is one reason testing another source can be useful.

Rate limiting

Servers sometimes limit how many requests a client can make during a particular period.

HTTP 429 means Too Many Requests and is specifically associated with rate limiting. A server may also provide a Retry-After header telling the client how long it should wait before making another request.

Do not try to defeat rate limits by repeatedly submitting the same request.

If a service is temporarily limiting requests, repeated attempts can make the situation worse.

Connection timeouts

A connection does not have to fail instantly to be considered broken.

A remote system can stop responding for long enough that the downloader's timeout is reached.

MediaFetches classifies several source/network errors, including timeout and connection-reset conditions, and its downloader has a configured socket timeout of 15 seconds with 3 general retries.

That does not mean every interruption lasts 15 seconds or that every failure will be retried three times in exactly the same way. It means the downloader has explicit timeout and retry behavior rather than waiting forever.

Large files

Large files expose interruptions that a small file may finish before you even notice.

A 20 MB file may complete during a brief period of good connectivity.

A multi-gigabyte video has to maintain successful transfer and server-side processing for much longer.

MediaFetches has a default maximum individual output size of 2 GB. That value is configurable through deployment settings; it is not an immutable MediaFetches rule.

Storage limitations

There are two different storage questions:

Server storage: Can MediaFetches temporarily store and process the finished file?

Device storage: Can your computer or phone save the finished file locally?

MediaFetches has a default temporary-storage ceiling of 8 GB. Its housekeeping system removes expired or orphaned files, and its disk-quota logic can evict older finished jobs when the configured total temporary-storage limit is exceeded.

Your own device can have a separate storage problem.

If the server successfully prepares the file but your device cannot save it, that is not the same as the source download failing.

Media stream or fragment interruptions

Modern media sources may deliver video through multiple streams or fragments.

The underlying yt-dlp configuration used by MediaFetches enables concurrent fragment downloading and retry behavior. yt-dlp documents separate retry handling for downloads and media fragments.

A problem affecting one fragment can therefore look different from a complete loss of the internet connection.

A transfer might pause while the downloader deals with a temporary source-side problem and then continue.

Temporary media URLs

Some media systems use temporary or signed URLs to provide access to the actual file.

For example, AWS documents that presigned URLs expire and that if a connection drops and a client tries to restart a download after the URL has expired, the request can fail.

This is an important distinction:

A source-access problem can occur even when your internet connection is healthy.

MediaFetches does not expose a generic "refresh the source URL" control for users, so if the underlying media access has become invalid, the legitimate solution may simply be to start a new controlled attempt later.

Browser, device, or network changes

A download can also be affected when the device changes network conditions or aggressively backgrounds an application.

This is especially relevant to mobile devices.

Android provides specific networking APIs for detecting changing connectivity and distinguishes network availability, metered networks, and background-data restrictions.

The safest approach is to avoid assuming that a phone which still shows a Wi-Fi icon necessarily has an uninterrupted path to the download server.

What It Means When the Download Is Stuck at 0%

A 0% download does not automatically mean the download has failed.

Possible explanations include:

the job is still queued preparation has not completed source extraction is taking time the source is temporarily unavailable the server is experiencing a temporary condition no usable progress percentage is available yet

MediaFetches explicitly supports an unknown percentage state. Its job representation can use a null percentage when an exact percentage is unavailable.

So the first question should be:

Does the job say "Waiting for a free slot," "Preparing your download," or "Downloading media"?

Those states tell you much more than a bare percentage.

What It Means When the Download Stops in the Middle

Suppose the download reaches 43% and stays there.

Do not immediately assume that 43% is a permanent failure point.

Possible causes include:

temporary Wi-Fi interruption mobile-network change source-server interruption a stalled media fragment temporary rate limiting connection timeout server-side processing or resource pressure storage limitations source media becoming unavailable a problem specific to that video

A useful test is to check another download.

If another unrelated video completes normally, the problem is more likely to be specific to the first source or media item.

If several different downloads stop around the same time, investigate the network or service conditions instead.

What It Means When the Download Is Stuck Near 100%

A download that appears stuck at 98% or 99% deserves a slightly different diagnosis.

The final portion can involve:

completing the final media bytes merging separate audio and video streams FFmpeg processing finalizing the output container writing the finished file checking that the expected output exists

MediaFetches explicitly separates downloading from processing, and its final video pipeline can use FFmpeg for MP4 processing.

So if the interface changes from Downloading media… to Processing media…, do not restart the job simply because the transfer percentage is no longer moving.

FFmpeg's documentation also notes that faststart performs a second pass to move MP4 indexing information to the beginning of the file, which is additional processing after the media data itself has been received.

Why Download Speed Can Temporarily Fall to Zero

Seeing 0 MB/s is concerning, but it is not proof of permanent failure.

A displayed transfer speed is normally calculated from recent byte movement.

If no new bytes arrive during a short measurement interval, the displayed speed can fall to zero even though the underlying process has not yet reached a final failure state.

There are several possible explanations:

the network temporarily stopped transferring the source paused or stopped responding a fragment is being retried the connection is being re-established the server is temporarily busy the download has moved into another stage the final processing stage has begun

This is why speed alone is not enough to diagnose a stalled download.

Look at the job state and message too.

A Practical Troubleshooting Sequence

When a download appears stuck, work through these steps in order.

1. Check whether the percentage is actually moving

Watch the progress for a little while rather than reacting to one unchanged number.

For example:

41.2% 41.4% 41.7%

is still progress.

The interface may update at intervals rather than continuously.

1. Check whether download speed is truly zero

If speed briefly shows zero and then returns, the transfer may simply be experiencing a temporary interruption.

If speed remains at zero and the job state also remains unchanged for a prolonged period, continue diagnosing rather than repeatedly pressing Download.

1. Check network stability

Try a simple comparison:

open several normal websites play a short online video run a normal connection-speed test check whether another large download behaves normally

If everything else is also struggling, investigate Wi-Fi, mobile data, router, or ISP conditions.

If everything else works normally, the problem may be further upstream.

1. Check whether another download works

This is one of the most useful isolation tests.

If:

Video A stops + Video B also stops

the problem may be your connection or the MediaFetches service.

If:

Video A stops + Video B completes

the first source or media item deserves more attention.

This is not absolute proof, but it gives you a useful direction.

1. Check the file size

A large file can take substantially longer to finish than a small one.

Also remember that a higher-resolution source can produce a much larger output.

Do not judge the transfer only by elapsed minutes.

Look at:

current percentage bytes downloaded total size speed whether the state is downloading or processing

1. Check whether the source is still available

If the original video has been removed, made private, restricted, or otherwise changed, a new attempt may fail even though your internet connection is perfect.

If the source page itself no longer works normally, there may be nothing to fix on your side.

1. Check the MediaFetches job state

This is especially important with MediaFetches.

The current job system distinguishes:

Queued — waiting for a server slot Preparing — setting up the download Downloading — receiving media Processing — final media processing Ready — finished file is available Failed — job could not be completed Cancelled — job was cancelled

These are not interchangeable conditions.

1. Consider temporary server or source conditions

If your network is stable and another download works, the problem may be upstream.

A source server can temporarily have delivery problems.

MediaFetches can also be handling other downloads.

The current default capacity is three simultaneous download processes, with up to twenty waiting jobs. If the waiting queue itself is full, the server returns a 503 busy response rather than allowing an unlimited queue.

HTTP 503 generally represents a service that is temporarily unable to handle a request, commonly because of maintenance or overload.

1. Wait when the evidence suggests a temporary interruption

Waiting makes sense when:

the state has not changed but the service has not reported failure speed briefly dropped to zero the source appears temporarily unavailable the server is processing the file the network has just changed a temporary service condition is likely

There is no universal number of seconds that guarantees recovery.

Do not use a fixed "wait exactly five minutes" rule. The correct waiting period depends on which stage is stalled.

1. Make one controlled new attempt

If the job eventually fails or the source condition has clearly changed, make one fresh attempt.

Do not continuously submit the same request.

Repeated requests can encounter rate limits and can also add unnecessary work to a busy server. HTTP 429 specifically exists to tell clients that they are sending too many requests and should slow down.

1. Know when the problem is upstream

Sometimes there is simply no legitimate user-side fix.

If:

your connection is working other downloads work the source is having a problem the MediaFetches server is overloaded the source media is no longer available the server-side job reaches its timeout the file exceeds the configured server limit

then changing browser settings repeatedly will not solve the underlying problem.

The right response is to wait, try a valid alternative source when appropriate, or try again later.

How MediaFetches Handles a Stalled Download

Understanding the actual implementation helps avoid incorrect troubleshooting advice.

Queue and concurrency

MediaFetches uses a bounded download queue.

The current defaults are:

3 simultaneous download processes 20 queued jobs 30-minute active-job timeout 2 GB maximum individual output 8 GB maximum temporary storage 30-minute finished-job TTL

These are configuration defaults, not permanent platform limits. Deployment environment variables can change them.

The 30-minute timeout starts after a job acquires a download slot and enters the active preparation/download pipeline. A job waiting in the queue is not using that active-job timeout yet.

Download progress

MediaFetches receives progress information from yt-dlp and exposes:

percentage downloaded bytes total bytes speed ETA

The server throttles progress events to four updates per second so that the client receives useful progress without an unnecessary stream of tiny updates.

Timeout behavior

The default job timeout is 30 minutes.

When that wall-clock limit is reached, MediaFetches aborts the download process and reports:

"This download took too long and was stopped."

That does not mean every slow transfer fails at exactly 30 minutes in every deployment. The timeout is configurable.

Source extraction and retries

The underlying yt-dlp configuration uses a 15-second socket timeout, 3 general retries, and 8 concurrent fragments.

That gives the download process some ability to recover from transient conditions, but it should not be described as unlimited automatic recovery.

Processing and FFmpeg

MediaFetches can download separate video and audio streams and then process them into the requested output.

For video, the current managed pipeline uses MP4 output and FFmpeg stream-copy processing with +faststart; it is not performing ordinary video compression/re-encoding during that step.

Therefore:

Downloading complete → Processing media → Ready

is a legitimate lifecycle.

Temporary files and cleanup

The server stores managed-job output under its jobs temporary directory.

Finished files are given an expiry time. A background janitor removes expired jobs and orphaned files, including files left behind after crashes or hard restarts. The disk-quota system also removes older finished files when the configured temporary-storage ceiling is exceeded.

Finished-file delivery and HTTP Range support

This is an important MediaFetches distinction.

After a job reaches Ready, the finished file is served through a dedicated file endpoint with:

Content-Length Accept-Ranges: bytes byte-range handling 206 Partial Content responses for valid ranges

HTTP Range requests are specifically designed for retrieving portions of an existing resource and are commonly used by download managers to resume interrupted transfers.

But this does not mean MediaFetches can automatically resume an interrupted source extraction from the exact point where the source stopped.

The Range support applies to the already-finished file being delivered from MediaFetches to the user.

That is fundamentally different from resuming the server's upstream extraction from the original source.

This distinction matters.

What You Should Not Do

If a download appears stuck:

Do not repeatedly press Download every few seconds. Do not assume 0 MB/s means permanent failure. Do not assume your internet is automatically the problem. Do not assume MediaFetches is automatically the problem. Do not assume a 99% display means exactly 1% of network transfer remains. Do not bypass rate limits or access controls. Do not change multiple network settings at once and then try to diagnose the result. Do not confuse server-side processing with network transfer. Do not confuse finished-file Range support with upstream source-resume support.

The goal is diagnosis first, retry second.

Quick Troubleshooting Checklist

When a download stops midway, use this order:

Check the current state. Queued? Preparing? Downloading? Processing? Check the percentage. Is it genuinely unchanged? Check the speed. Is it briefly zero or continuously zero? Check the network. Are other websites and downloads working? Test another download. Does another source complete? Check the file size. Is this a very large video? Check the original source. Is the media still available? Consider MediaFetches capacity. Could the service be queued or temporarily busy? Wait if the evidence suggests a temporary interruption. Make one controlled new attempt if appropriate. If the same source repeatedly fails while everything else works, treat it as a source-specific problem rather than endlessly changing your own settings.

Frequently Asked Questions

Why is my video download stuck at 99%?

Near 100%, the system may still be receiving the final bytes or processing the completed media.

With MediaFetches, downloading and processing are separate states. Video processing can involve FFmpeg work after the source transfer itself has completed.

Why did my download speed become 0 MB/s?

Zero speed can mean that no new bytes were measured during a particular interval. It can happen during a temporary network interruption, source delay, retry, or stage transition.

Look at the job state instead of treating the speed number alone as proof of failure.

Can a download recover after a temporary interruption?

Sometimes.

Network and media download systems can retry temporary failures, and yt-dlp supports retry mechanisms for downloads and fragments.

However, recovery is not guaranteed.

Does MediaFetches automatically resume a partially downloaded source?

Do not assume that it does.

The MediaFetches job system supports a finished-file endpoint with HTTP Range requests, but that applies after the server has produced the finished file.

The managed source-download pipeline itself is not a user-facing pause/resume system for partially extracted source media. Its current yt-dlp configuration also uses noPart: true, so you should not describe it as a guaranteed upstream resume mechanism.

Why does the download stop during processing?

Downloading and processing are separate stages.

For example, MediaFetches may need to combine media streams or perform final MP4 processing with FFmpeg. The job can therefore stop showing normal transfer progress while processing continues.

What if the problem keeps happening with one specific video?

Test another source or video.

If other downloads complete normally, the problem may be specific to that source, its media streams, availability, access conditions, or the way the source currently delivers the media.

If every download has the same problem, investigate your network or the MediaFetches service instead.

Related MediaFetches guides

For related guidance, see why video downloads fail and download restart troubleshooting.

Final Takeaway

A download that appears stuck is not always a failed download.

The most useful first question is:

Is it waiting, preparing, downloading, processing, ready to save, or actually failed?

Once you know the stage, the possible causes become much narrower.

A temporary zero-speed period may recover. A queued job may simply be waiting for server capacity. A download near 100% may be processing rather than transferring. A source-side interruption may have nothing to do with your internet. And a finished file can have different behavior again when it is being delivered to your device.

Diagnose the stage first. Then troubleshoot the specific problem instead of repeatedly restarting everything.