> ## Documentation Index
> Fetch the complete documentation index at: https://docs.videodb.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Upload Troubleshooting

> Which links can be uploaded, how to share Google Drive files, and what each upload error means

## Quick Check

Open the link in a private or incognito browser window, without signing in. If the file plays or starts downloading, VideoDB can usually upload it. If you see a sign-in page, a "request access" page or a folder view, the upload will fail.

***

## What Works

| Source | Works | Notes |
| :- | :- | :- |
| Local file | Yes | Video, audio, or image (`png`, `jpg`, `jpeg`, `webp`) |
| Direct file URL | Yes | A link that returns the file itself, such as `https://example.com/video.mp4` |
| Presigned S3 / GCS / Azure URL | Yes | Only until the link expires. Make the expiry longer than the upload takes |
| HLS stream (`.m3u8`) | Yes | Recorded (VOD) streams |
| YouTube video | Yes | Public and unlisted videos. New video uploads use up to 480p on non-Pro plans and up to 720p on Pro. Lower-resolution sources keep their available resolution |
| Other public video pages | Usually | Depends on the platform. The page must be viewable without signing in |
| Google Drive file | Yes | Only when shared with **Anyone with the link**. See [Google Drive](#google-drive) |
| Dropbox file | Yes | Use a public single-file share link. Keep any sharing parameters in the URL |
| Wikimedia Commons | Yes | Use a Commons file page, a `Special:FilePath` link or the file URL on `upload.wikimedia.org` |
| TikTok video | Yes | Use the public post URL |

## What Doesn't Work

| Source | Why | What to do |
| :- | :- | :- |
| Private, members-only or age-restricted videos | The platform blocks access | Upload the file directly |
| Live streams that are still running | There's no finished file yet | Upload after the stream ends, or use [RTSP ingest](https://docs.videodb.io/pages/ingest/live-streams/rtsp-ingest.md) for live video |
| Playlists and channel pages | They link to many videos | Upload each video URL separately |
| Google Drive folders | They link to many files | Share and upload each file separately |
| Google Docs, Sheets or Slides | They are documents, not media | Export the media and upload the file |
| Pages that need a sign-in | We can't sign in on your behalf | Make the file public, or upload it directly |
| Web pages that only *show* a player or a download button | The link points to a page, not the file | Use the direct file link, or upload the file directly |
| Expired presigned links | The signature is no longer valid | Generate a new link |

> [!TIP]
>
> If a link can't be made public, download the file yourself and upload it with `file_path` (Python) or `uploadFile` (Node.js). Local uploads don't depend on how the file is shared.

***

## Google Drive

**1. Open the sharing settings**

In Google Drive, right-click the file and choose **Share**.

**2. Allow anyone with the link**

Under **General access**, change **Restricted** to **Anyone with the link**. **Viewer** is enough.

**3. Copy the file link**

Click **Copy link**. It looks like `https://drive.google.com/file/d/<FILE_ID>/view?usp=sharing`.

**4. Upload the link**

Pass the link as `url`. Links in the forms `drive.google.com/file/d/<FILE_ID>/...`, `drive.google.com/open?id=<FILE_ID>`, `drive.google.com/uc?export=download&id=<FILE_ID>` and `drive.usercontent.google.com/download?id=<FILE_ID>` all work. VideoDB imports the original file at its full resolution, whether it's a video, audio or image.

```python Python theme={null}
video = coll.upload(url="https://drive.google.com/file/d/<FILE_ID>/view?usp=sharing")
```

```javascript Node.js theme={null}
const video = await coll.uploadURL({
  url: "https://drive.google.com/file/d/<FILE_ID>/view?usp=sharing"
});
```

**If it still fails:**

* **Folder link** (`/drive/folders/...`): open the folder, then share and upload each file on its own.
* **Workspace account**: your organization may block sharing outside the company. Ask your admin, or download the file and upload it directly.
* **Shared drive**: the shared drive's settings can block link sharing even when the file allows it. Check with the drive's manager.
* **Popular file**: Google limits how often a shared file can be downloaded. If the file has been downloaded many times recently, wait and retry, or upload it directly.
* **Google Docs, Sheets or Slides**: these are documents, not media files.

***

## Upload Errors

When an upload fails, the SDK raises an error that carries the message below. Python raises `InvalidRequestError` and Node.js throws `VideodbError`. If you pass a `callback_url`, the callback carries both the message and a stable `error_code`, which is the better choice for handling errors in code.

```python Python theme={null}
from videodb.exceptions import InvalidRequestError

try:
    video = coll.upload(url=url)
except InvalidRequestError as e:
    print(e)  # Invalid request: No file was found at this URL. ...
```

```javascript Node.js theme={null}
import { VideodbError } from 'videodb';

try {
  const video = await coll.uploadURL({ url });
} catch (e) {
  if (e instanceof VideodbError) console.error(e.message);
}
```

Failed callback payload:

```json theme={null}
{
  "success": false,
  "error_code": "access_denied",
  "message": "We don't have permission to access this URL. Make sure the file is public or shared with anyone who has the link. If it's a signed or temporary link, it may have expired; generate a new one.",
  "callback_data": {}
}
```

### Problems with the link

| `error_code` | Message | Why it happens | How to fix it |
| :- | :- | :- | :- |
| `url_not_found` | No file was found at this URL. Check that the link is correct and the file hasn't been deleted. | The address returns "not found". Usual causes are a typo or a deleted file | Check the link in a private browser window |
| `access_denied` | We don't have permission to access this URL. Make sure the file is public or shared with anyone who has the link. If it's a signed or temporary link, it may have expired; generate a new one. | The file exists but requires a sign-in or permission, such as a Google Drive file that isn't shared, or a presigned link that has expired | Make the file public or "anyone with the link" (for Drive, follow [the steps above](#google-drive)), generate a fresh presigned link, or upload the file directly |
| `url_unreachable` | We couldn't reach the server at this URL. Check the link and try again. | The domain doesn't exist or the server refused the connection | Check the domain for typos. If the server is on a private network or behind a VPN, upload the file directly |
| `unsupported_url` | We can't fetch media from this URL. Use a direct link to a video, audio or image file, or upload the file itself. | The link points to a web page or a folder, not a media file | Use the direct file link, or upload the file directly |
| `no_media_found` | No video, audio or image was found at this URL. If it's a share page, use a direct download link instead. | The page opened but contains no media we can fetch, which is common with share pages | Use a direct download link, such as Dropbox's `?dl=1` form |
| `unsupported_media` | The file at this URL isn't a video, audio or image file we can read. If the link opens a web page, such as a share page, use a direct download link instead. | The download finished, but the file is a web page, a document, or a corrupted or unsupported file | Open the file locally to check it plays. Check the link returns the file itself, not a page |

### Problems with the platform

These come from the platform hosting the video (YouTube, Instagram and others). The video's owner or the platform controls them.

| `error_code` | Message | Why it happens | How to fix it |
| :- | :- | :- | :- |
| `private_video` | This video is private and cannot be accessed. | The owner made the video private | Ask the owner to make it public or unlisted, or upload the file directly |
| `members_only` | This video is available only to channel members and cannot be imported. | The video is limited to paying channel members | Upload the file directly |
| `age_restricted` | This video is age-restricted and cannot be imported. | The platform requires a signed-in, age-verified viewer | Upload the file directly |
| `geo_restricted` | This video is unavailable in the region used for downloading. | The owner or platform limits the video to certain countries | Upload the file directly |
| `video_unavailable` | This video is unavailable and cannot be imported. | The video was removed, blocked, or never existed | Check the link plays in a browser |
| `live_video` | Live streams can't be uploaded. Try again after the stream has ended. | The stream is still live, so there's no finished file | Retry after it ends, or use [RTSP ingest](https://docs.videodb.io/pages/ingest/live-streams/rtsp-ingest.md) for live video |
| `upcoming_live_video` | This live event hasn't started yet. Try again after it has ended. | The event is scheduled but hasn't started | Retry after the event ends |
| `ended_live_video` | This live event's recording isn't available yet. Try again later. | The stream ended, but the platform is still preparing the recording | Retry later |
| `download_timeout` | This file took too long to download. Try again later, or upload the file directly. | The source took too long to deliver the file | Retry later. If the transfer keeps timing out, download the file and upload it directly |
| `source_fetch_failed` | We couldn't fetch media from this link right now. If it's private or needs a login, make it public; otherwise try again in a few minutes. | The platform didn't return the video. The post may need a sign-in (common for restricted Instagram posts), or the platform may be temporarily limiting requests (HTTP 429) | Check the post is viewable without signing in, then retry in a few minutes. If it keeps failing, upload the file directly |

### Problems with your account

| `error_code` | Message | Why it happens | How to fix it |
| :- | :- | :- | :- |
| `low_credit` | Insufficient credit: your balance is \$X. Please add credits to continue. | Your balance is too low to store new media | Add credits in the [VideoDB console](https://console.videodb.io) |

> [!NOTE]
>
> If you see `upload_failed`, or a message not listed here, the problem is usually on our side. Retry the upload. If it keeps failing, contact support with the URL and the time of the attempt.

***

## Next Steps

> [card] [Upload Video](https://docs.videodb.io/pages/ingest/files-and-collections/upload-video.md)
>
> Upload methods, media types and callbacks

> [card] [Collection Patterns](https://docs.videodb.io/pages/ingest/files-and-collections/collection-patterns.md)
>
> Batching, retries, and production patterns


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.