Video Download Troubleshooting Checklist: A Complete Step-by-Step Guide

Before You Change Anything: Identify the Exact Symptom

When a video download is not behaving normally, the first mistake is to treat every problem as a generic “download error.”

A download can fail before it starts, become slow while transferring, stop halfway, repeatedly restart, finish downloading but fail during processing, save incorrectly on one device, or produce a file that cannot play.

Those are different problems.

A useful troubleshooting model is:

SOURCE ↓ MEDIAFETCHES ↓ NETWORK ↓ BROWSER / APP ↓ DEVICE STORAGE ↓ MEDIA PLAYER ↓ PLAYBACK

The first job is to identify where the chain stops.

Download never starts

Ask:

Did MediaFetches accept the URL? Did a job get created? Is the job queued? Is it still preparing? Did an error appear immediately?

Do not begin by changing video quality if the URL was never successfully accepted.

Download is slow

Check whether the transfer is actually slow or whether the file is simply large.

Your internet plan, the network path, MediaFetches, and the original source can all influence throughput. Microsoft similarly recommends checking the network and comparing downloads from other sources when diagnosing download problems.

Download is stuck

A frozen percentage can mean a temporary interruption, a processing stage, or a genuine failure.

A job showing no movement at one instant is not enough information.

Download keeps restarting

This is different from merely being stuck.

A retry inside the downloader is not necessarily a new MediaFetches job.

A new job created by pressing Download again is also different from an internal retry.

Look for whether the job itself changed before assuming everything started from zero.

Unsupported source or format

Ask whether:

the URL is valid the platform is generally supported this particular media item is accessible usable formats were actually exposed the requested quality exists

A browser being able to open the page does not guarantee that a downloader can extract its media. yt-dlp's documentation explicitly notes that listed site support is not a guarantee that every URL will work.

Video downloads without sound

This may be a media-stream problem rather than a speaker or player problem.

Some sources provide video and audio separately, and the final output requires those streams to be combined.

Download works on one device but not another

Separate:

server preparation

from:

saving the file

from:

playing the file

A phone running out of storage has a different problem from a laptop successfully saving a file that uses an unsupported codec.

Download finishes but the file will not play

First verify that the same complete file exists on both devices.

Then investigate:

container codec player decoder device capability

MDN distinguishes media containers from codecs and documents current browser codec compatibility.

Understand the Download Lifecycle

The current MediaFetches project gives a managed job a distinct lifecycle.

Queued

The job is waiting for a download slot.

The current/default configuration permits 3 simultaneous download processes and 20 queued jobs.

The user-facing message is:

“Waiting for a free slot…”

This is a capacity state, not proof that the user's internet is slow.

Preparing

The system is setting up the source and download process.

The current message is:

“Preparing your download…”

Do not interpret this stage as ordinary byte transfer.

Downloading

This is the active media-transfer stage.

MediaFetches can report:

percentage downloaded bytes total bytes when known speed estimated remaining time

The percentage can be unknown when the downloader cannot determine an exact total.

Processing

After the source transfer, MediaFetches can enter:

“Processing media…”

This can include FFmpeg work such as combining separate streams or preparing the final MP4 output.

Ready

The current message is:

“Ready to save”

At that point, MediaFetches has a finished server-side file that can be requested through its file endpoint.

Failed or cancelled

The terminal states include:

Failed

and:

Cancelled

The current project distinguishes these from normal downloading and processing states.

That distinction matters because a browser problem, a source problem, and a cancelled job do not need the same fix.

The Master Troubleshooting Flow

The core method is:

OBSERVE → IDENTIFY STAGE → ISOLATE LAYER → TEST ONE VARIABLE → FIX → RETRY ONCE → STOP WHEN APPROPRIATE

Step 1: Check the URL

Make sure the URL is:

complete the intended video/page publicly accessible not malformed

MediaFetches validates URLs as public HTTP or HTTPS resources and rejects credentials/private destinations.

If the URL itself is wrong, no later troubleshooting step will matter.

Step 2: Check whether the source is accessible

Open the original URL normally.

Ask:

Does the intended page still exist? Does the video still play? Is it public? Does it now require login? Has it been removed? Is it restricted?

A source that is no longer accessible cannot be repaired by changing the browser's download settings.

Step 3: Check whether the source is supported

MediaFetches relies on yt-dlp for source extraction.

The current project contains configured platforms, but the presence of a platform in that configuration is not the same as a guarantee that every URL on the platform will work.

yt-dlp itself warns that websites change and that individual URLs still need to be tested.

Step 4: Check the MediaFetches job state

This is one of the most important steps.

Ask whether the job is:

queued

preparing

downloading

processing

ready

or:

failed / cancelled

Do not troubleshoot a queued job as though it were a network failure.

Do not troubleshoot a processing job as though its source transfer were still running.

Step 5: Check the network

Test the actual network rather than trusting one device indicator.

Try:

opening several unrelated websites a legitimate large download from another service another authorized video source another network, if available

Microsoft recommends testing another website or network when distinguishing network problems from site-specific download failures.

Step 6: Test another source

This is one of the highest-value tests.

Same device + different source

If another source works, the original media/source becomes a stronger suspect.

If unrelated sources all fail, investigate the shared environment instead.

Step 7: Check available storage

A device can successfully communicate with MediaFetches but still be unable to save a large file.

Check the destination device's free space.

Chrome explicitly treats Disk full as a local download failure caused by insufficient space. Mozilla likewise documents storage and download-folder problems as causes of failed downloads.

Step 8: Check available quality or format

If MediaFetches successfully reads the source, inspect the qualities it actually offers.

Do not assume:

every video has 1080p every source has 4K every representation has the same encoding changing quality can fix an unsupported source

A smaller available quality can help when the problem is size or a particular representation, but it does not create missing source support.

Step 9: Check audio and video selection

For sources that expose separate streams, ask whether:

usable video exists usable audio exists the selected combination can be processed

yt-dlp documents separate bestvideo and bestaudio selection and the use of FFmpeg when separate streams need to be merged.

Step 10: Check browser behavior

A browser can introduce a separate problem after MediaFetches has prepared the file.

Check:

download destination blocked downloads permissions browser settings security software whether another browser behaves the same way

Firefox's current support documentation specifically recommends checking the Downloads panel, download folder, file-type behavior, and security software when downloads cannot be saved.

Step 11: Check device compatibility

If the file saves but does not play, move the investigation to:

container → codec → player → decoder → device

Do not assume that the filename alone determines compatibility.

Step 12: Check whether the downloaded file is complete

Compare:

file size extension whether the file opens whether playback fails immediately or partway through

If one device has a tiny partial file and the other has the full file, you are not actually testing the same media.

Step 13: Check playback compatibility

If the complete file exists, test another media player.

This isolates:

file compatibility

from:

player compatibility

MDN's current media documentation explains that container and codec are separate parts of the playback chain.

Step 14: Consider processing or FFmpeg issues

If the transfer completes but MediaFetches remains in:

Processing media…

the issue may be server-side media processing.

For the current MediaFetches video workflow, FFmpeg is used for managed post-processing, including stream-copy MP4 handling and +faststart.

A processing problem is not automatically a network problem.

Step 15: Consider temporary source or extractor problems

Source platforms change.

Extractors therefore sometimes need updates.

The current MediaFetches project includes a best-effort yt-dlp update-and-retry mechanism after extraction failure, with a one-hour cooldown between automatic update attempts.

This is a recovery mechanism, not a guarantee.

An update can fix an extractor that has fallen behind a platform change, but it cannot make every unsupported source universally supported.

Step 16: Make one controlled retry

Retry only after you know why you are retrying.

Examples:

Network unstable → reconnect first.

Storage full → free space first.

Server queue → wait for capacity.

Temporary source issue → try later.

Failed job → make one fresh attempt.

Do not repeat the same request continuously.

HTTP 429 exists specifically for excessive request rates, and Retry-After can tell clients how long to wait.

Step 17: Know when to stop

Stop troubleshooting from the client side when the evidence points to:

unsupported source inaccessible/private content DRM protection unavailable media server capacity a source-side problem a server-side processing problem a deployment configuration limit

A good troubleshooting workflow includes knowing when nothing you can change locally will fix the underlying problem.

Troubleshooting by Symptom If the download does not start

Check:

URL source accessibility source support MediaFetches job creation queue/preparation state

If the server never reaches an active job, do not start by reinstalling browsers or changing playback software.

If the download is very slow

Check:

actual network throughput file size competing traffic Wi-Fi/mobile conditions source speed MediaFetches queue temporary server conditions

For detailed speed diagnosis, see our current slow-download guide.

If the download stops midway

First distinguish:

stopped temporarily

from:

job failed

Look at the job state and whether bytes eventually continue changing.

If the same problem happens on every source, investigate the network or service.

If it happens on one source only, investigate the source.

If the download keeps restarting

Ask whether:

the speed merely dropped the downloader retried an operation the job actually failed a brand-new job was created

A retry is not automatically a complete restart.

For the detailed distinction between restarting and retrying, see the relevant troubleshooting article once that newer article is present in the live project.

If the source is unsupported

Check the exact URL and whether the original source is accessible.

If MediaFetches cannot identify a usable media source through its extraction pipeline, changing resolution is unlikely to create support that does not exist.

If the format is unsupported

Do not rename file extensions.

A .webm file renamed to .mp4 is still the same underlying media.

A real conversion requires media processing.

If the downloaded video has no sound

Check:

whether the source contains audio whether the selected representation includes audio whether separate audio was available whether processing completed whether the player can decode the resulting audio track

For more detail on separate media streams, see our guide to MP4 vs WebM and the dedicated audio/video-processing article once its current URL is published.

If the file is too large

Check both sides:

Device

Does the destination have enough free space?

MediaFetches

The current/default managed-download limit is 2 GiB per output file.

The project can return:

“That file is larger than this server allows. Please try a lower quality.”

A smaller available quality may help if the source provides one.

If the problem happens only on one device

Run:

same device + different source

then:

same source + different network

then:

same completed file + different player

This lets you determine whether the problem follows the source, network, device, file, or player.

If the file downloads but will not play

First confirm the file is complete.

Then investigate:

container codec codec profile/level where relevant player decoder operating-system media support

Do not assume the .mp4 extension means every MP4 file is equivalent.

If the download reaches 100% but stays processing

Wait long enough to determine whether the state actually changes.

MediaFetches separates downloading and processing.

If the job is processing, server-side FFmpeg work may still be happening.

If it eventually fails, treat the result as a processing/server problem rather than automatically blaming the network.

How to Tell Whether the Problem Is Your Side or the Server's Side Signs of a device problem only one device fails another device saves the same file normally the failing device is low on storage another file also cannot be saved the problem appears only with one local download folder

Chrome and Firefox both document disk space, download folders, permissions, and local security settings as possible causes of download failures.

Signs of a browser problem one browser fails but another works on the same device the browser blocks the download download-folder behavior differs security settings interfere file-type handling differs

Mozilla's current guidance specifically includes download-folder and file-type settings in troubleshooting.

Signs of a network problem several unrelated downloads fail or slow down the problem disappears on another network Wi-Fi is unstable mobile data behaves differently other websites also struggle Signs of a source problem only one video fails other videos from unrelated sources work the original page is unavailable the source recently changed its behavior available media formats are unusual or incomplete Signs of a MediaFetches server problem unrelated sources fail at the same time jobs remain queued because capacity is exhausted the service returns a busy response processing repeatedly fails for otherwise valid sources the device and network work normally elsewhere

The current MediaFetches configuration uses a default concurrency of 3 and a maximum queued-job count of 20.

When the queue is full, the project returns:

“The server is busy right now. Please try again in a minute.”

Those are server-capacity conditions, not user-internet conditions.

The One-Variable Testing Method

This is the single most useful habit in troubleshooting.

Change one variable at a time.

Same device + different source

If:

Source A fails

and:

Source B works

the source or media item becomes more suspicious.

Same source + different network

If:

Wi-Fi fails

but:

mobile hotspot works

the network path becomes a stronger suspect.

Microsoft explicitly recommends trying another network to help distinguish network-level problems from website-specific failures.

Same file + different player

If the same complete file plays in one player but not another, the player or decoder becomes the stronger suspect.

Same device + different browser

If Chrome fails but Firefox works on the same computer, the browser/download layer deserves attention.

Do not simultaneously change the browser, network, file quality, and source. You lose the information that would have told you which variable mattered.

Common Mistakes That Make Troubleshooting Harder Repeatedly pressing Download

This can create additional jobs and requests without fixing the original cause.

If rate limiting is involved, repeated requests are particularly unhelpful.

Changing several settings at once

You may solve the problem without learning what caused it.

Then the same issue returns later.

Assuming 0 MB/s always means failure

A temporary zero-speed measurement can occur without a permanent failure.

Check the state and whether the transfer resumes.

Assuming 99% always means the file is broken

Near the end, a system may still be finalizing or processing the result.

Blaming the device before testing the network

Two devices can simply be using different networks.

Renaming file extensions

Renaming .webm to .mp4 does not convert the media.

Assuming higher quality is always better

The highest available quality may be unnecessarily large for your device or storage situation.

Trying to bypass restrictions

Do not attempt to bypass:

DRM paywalls private access login requirements anti-bot systems access controls rate limits

If the source legitimately requires access that MediaFetches does not support, stop there.

MediaFetches-Specific Troubleshooting Checklist URL validation

The current server accepts public HTTP/HTTPS URLs and rejects credential-bearing/private/internal destinations.

If the URL is not valid, fix the URL first.

Source extraction

MediaFetches uses yt-dlp for source extraction.

The extractor can encounter unavailable, private, restricted, unsupported, or temporarily changed sources.

Quality selection

MediaFetches builds quality options from formats returned by the source.

It does not invent a 4K stream that the source does not provide.

Audio and video processing

The current video workflow can use a combined source format when available or select separate video and audio streams and process them through FFmpeg.

Job states

The current managed lifecycle is:

queued → preparing → downloading → processing → ready

with:

failed

and:

cancelled

as terminal alternatives.

Timeouts and retries

Current/default configuration includes:

15-second yt-dlp socket timeout 3 general yt-dlp retries 30-minute active job timeout 8 concurrent fragments

These are configuration/implementation values, not guarantees that every source will succeed.

File-size limit

Current/default:

2 GiB maximum individual output

Temporary storage

Current/default:

8 GiB configured READY-file quota

This quota is enforced against tracked READY job files; it should not be described as a literal filesystem ceiling over every active temporary byte.

Finished-file retention

Current/default:

30-minute finished-job TTL

Cleanup

Current/default:

5-minute housekeeping sweep

The project removes expired job files and orphaned files and can evict older READY files when the configured quota requires it.

Finished-file delivery

The finished file endpoint sends:

Content-Type Content-Disposition Content-Length Accept-Ranges Cache-Control X-Content-Type-Options

Range requests can receive 206 Partial Content.

MDN documents Range requests as useful for download managers that support interrupted-download recovery.

Device and native download paths

The project currently uses different local-save mechanisms:

Web: browser download

Android: Android DownloadManager

iOS: URLSessionDownloadTask, followed by the system Share Sheet

Android's official DownloadManager documentation describes it as a system service for long-running HTTP downloads, including handling background transfers and connectivity-related retry behavior.

Apple's URLSessionDownloadTask provides a separate native download model and supports resumption where the server/client conditions allow it.

This is why a device-specific saving problem can exist even when the MediaFetches backend is healthy.

A 60-Second Quick Checklist

When you have no time for a long investigation, use this order:

✅ URL is correct

✅ Original source opens normally

✅ Source is public and accessible

✅ MediaFetches can read the source

✅ Job state is understood

✅ Network is stable

✅ Device has enough free space

✅ Requested quality actually exists

✅ Audio/video streams are available when required

✅ Browser or native download can save the file

✅ Finished file is complete

✅ Player supports the file

✅ Only one variable was changed during the test

✅ One controlled retry was attempted

✅ No access restriction was bypassed

The goal is not to complete every check every time.

The goal is to stop as soon as you have enough evidence to identify the failing layer.

When to Contact the Site Administrator or Treat the Issue as a Service Problem

Contact the site administrator when several independent tests point to the server.

Examples include:

multiple unrelated public sources fail processing repeatedly fails the service reports a busy condition server storage or configuration limits are being reached the job repeatedly times out a deployment has an unavailable downloader/FFmpeg dependency the same valid source works elsewhere but consistently fails in the current deployment

Give the administrator useful evidence:

source URL approximate time of failure job state whether another source worked whether another device/network worked exact user-facing error whether the problem happened during downloading or processing

Avoid sending passwords, cookies, authentication tokens, or private credentials.

Common Questions What should I check first when a video will not download?

Start with the URL and source.

Then check the MediaFetches job state.

Only after that should you move to network, browser, storage, and playback checks.

How do I know if the problem is my internet?

Test another legitimate large download and, when practical, the same download on another network.

If unrelated downloads are also failing, the network becomes a stronger suspect.

How do I know if the source is the problem?

Try another public source.

If other sources work while the same one repeatedly fails, the original source becomes a stronger suspect.

That does not prove the source is at fault, but it narrows the investigation.

What if every video fails?

Look at the shared layers:

network → MediaFetches → deployment

If unrelated sources all fail, do not spend an hour changing playback settings.

What if only one video fails?

Check:

source availability access restrictions available media formats source-specific extraction behavior

A platform can generally work while one particular media item does not.

What if the download works on my PC but not my phone?

First determine whether the phone:

cannot retrieve the file cannot save the file saves it but cannot play it

Then compare:

same device + different network

and:

same completed file + different player

What if the video downloads but has no sound?

Check whether audio was available and whether the final processing stage completed.

If the source uses separate audio/video streams, the merge stage can matter.

What if the download reaches 100% and does not finish?

Check whether the job has changed to:

Processing media…

If it has, the source transfer may be complete and FFmpeg/finalization may still be running.

Should I keep retrying the same URL?

No.

Make a controlled retry after identifying the likely cause.

Repeated rapid requests can add load and may trigger rate limiting.

When should I stop troubleshooting?

Stop when the evidence clearly points to:

an unsupported source an access restriction DRM an unavailable media item a server-side problem a deployment limitation

A good troubleshooting process is not endless.

Knowing when the problem is outside your control is part of solving it.

Related MediaFetches guides

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

Final Takeaway

A broken download is rarely explained by one generic sentence such as:

“Your internet is bad.”

The actual path is:

SOURCE ↓ MEDIAFETCHES ↓ NETWORK ↓ BROWSER / APP ↓ DEVICE STORAGE ↓ MEDIA PLAYER ↓ PLAYBACK

A problem can occur at any of those layers.

That is why the most reliable approach is:

OBSERVE → IDENTIFY STAGE → ISOLATE LAYER → TEST ONE VARIABLE → FIX → RETRY ONCE → STOP WHEN APPROPRIATE

Start with the simplest evidence.

Check the URL.

Check the source.

Check the MediaFetches job state.

Check the network.

Check storage.

Check the browser or native saving path.

Then, only after the same complete file exists, investigate playback compatibility.

The current MediaFetches implementation follows this separation in its job lifecycle and delivery architecture: queued, preparing, downloading, processing, ready, failed, or cancelled, with a separate finished-file endpoint and different web/Android/iOS saving paths.

The most useful troubleshooting question is therefore not:

“Why isn't my download working?”

It is:

“What is the first layer where the expected behavior changes?”

Once you find that layer, the next action usually becomes much clearer.