Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/damianiglesias/omniform/llms.txt

Use this file to discover all available pages before exploring further.

This page covers the most common issues you may encounter when using or developing Omniform, and how to resolve them. Issues are grouped by the phase in which they occur — first-launch dependency setup, runtime download problems, and development/build failures. If your issue is not listed here, check the yt-dlp and Tauri issue trackers, as many platform-specific edge cases are documented there.
Cause: No internet connection, or the binary host is temporarily unavailable.Omniform downloads yt-dlp and ffmpeg from third-party hosts on first launch:
Platformyt-dlp sourceffmpeg source
WindowsGitHub releasesgyan.dev
macOSGitHub releasesevermeet.cx
LinuxGitHub releasesjohnvansickle.com
Fix:
  1. Verify your internet connection.
  2. Click the Retry button in the dependency banner that appears at the top of the app window.
  3. If the issue persists, check whether the relevant ffmpeg mirror is reachable in your browser:
  4. If a mirror is down, see the “ffmpeg source URL is unavailable” item below for a developer workaround.
Cause: The app was unable to complete dependency setup, or setup was interrupted before yt-dlp was confirmed ready.Fix:
  1. The dependency banner should appear automatically when the app detects that yt-dlp is missing. If it does, click Install or Retry and wait for the setup to complete.
  2. If the banner does not appear, re-launch the app. Omniform calls ensure_dependencies on startup and will show the banner if either binary is missing.
  3. Do not start downloads until both ytDlpReady and ffmpegReady are true in the DependencyStatus returned by check_dependencies.
Cause: The URL is invalid, the video is private or geo-restricted, or yt-dlp does not support that platform.The download://error event payload contains the raw stderr output from yt-dlp, which usually describes the problem precisely.Fix:
  1. Open the URL in your browser and confirm the video plays and is publicly accessible.
  2. If the video is geo-restricted, yt-dlp may not be able to bypass the restriction without additional configuration (e.g. cookies or a VPN) that Omniform does not expose.
  3. Check whether yt-dlp supports the platform at https://github.com/yt-dlp/yt-dlp/blob/master/supportedsites.md.
  4. Try a different URL from the same platform to rule out a video-specific issue.
Cause: ffmpeg is merging or re-encoding the video and audio streams. For high-resolution video or audio formats that require transcoding (e.g. converting to WAV or FLAC), this step can take several minutes on slower machines.Fix:
  1. Wait. The conversion step is CPU-bound and cannot be sped up from within the app.
  2. If the progress bar has been stuck for more than 10–15 minutes without any change, the ffmpeg process may have stalled.
  3. Click Cancel on the affected download and try again. If the problem recurs, try a lower quality setting or a different output format.
Choosing an audio format like WAV or FLAC for a long video will produce a very large file and a correspondingly long conversion step. MP3 or M4A are faster to encode.
Cause: The selected output folder is no longer accessible (e.g. a removable drive was ejected), or the filename generated by yt-dlp contained characters that caused a filesystem error.Fix:
  1. Open the output folder in your file manager and confirm it exists and is writable.
  2. If the path is no longer valid, use the folder picker in Omniform to select a new output directory.
  3. Try a simple, well-known path such as the Desktop or the system Downloads folder.
  4. Re-run the download. The download://done event’s outputPath field contains the exact directory yt-dlp was told to write to — check whether that path exists on disk.
Cause: The Vite development server is not running, there is a Rust compilation error, or a required system dependency is missing.Fix:
1

Check the terminal output

Run npm run tauri dev in a fresh terminal session. Rust compiler errors are printed to stderr before the window opens. Fix any errors and try again.
2

Verify Node.js and Rust versions

Omniform requires Node.js 18+ and a recent stable Rust toolchain. Run node --version and rustc --version to confirm.
3

Check Tauri system prerequisites

Tauri requires platform-specific system libraries. Follow the official checklist for your OS at https://tauri.app/start/prerequisites/.
4

Restart the dev server

Kill any running Tauri or Vite processes, then run npm run tauri dev again from the project root.
Cause: Missing Tauri system dependencies for the current platform, a mismatched Rust toolchain, or an outdated rustup installation.Fix:
  1. Ensure your Rust toolchain is up to date: 
    rustup update
  2. Re-read the platform prerequisites in the Tauri documentation: https://tauri.app/start/prerequisites/
  3. On Linux, confirm all required system packages (WebKit2GTK, build-essential, etc.) are installed for your distribution.
  4. On macOS, confirm Xcode Command Line Tools are installed: 
    xcode-select --install
  5. On Windows, confirm the Microsoft C++ Build Tools and WebView2 Runtime are installed.
Tauri v2 requires a different set of system packages than Tauri v1. If you have previously worked with Tauri v1 projects, re-check the v2 prerequisites before assuming your environment is correctly configured.
Cause: On some Linux desktop environments the clipboard is only accessible while a clipboard manager daemon is running. On macOS and Windows this issue does not typically occur.Fix:
  • The clipboard auto-paste feature is non-critical. You can always paste a URL manually into the URL input field.
  • Errors from the clipboard read are silently ignored — the app will not show an error or crash if clipboard access is unavailable.
  • If you want clipboard auto-paste to work on Linux, ensure a clipboard manager such as xclip, xsel, or a desktop environment clipboard daemon is running.
Cause: The third-party ffmpeg build hosts (gyan.dev, evermeet.cx, johnvansickle.com) are community-maintained. They may occasionally go offline, change directory structures, or rename files.This is a developer-level issue that requires a source code change and a new build.Fix:
1

Identify the correct mirror URL

Find a reliable alternative ffmpeg static build for your target platform. The ffmpeg project’s official download page at https://ffmpeg.org/download.html links to trusted third-party builds.
2

Edit the download URL in source

Open src-tauri/src/dependencies.rs and update the ffmpeg_download_url() function to return the new URL for the affected platform.
3

Rebuild the app

Run npm run tauri build to produce a new distributable with the updated URL baked in.
For full details on how Omniform resolves and downloads its dependencies, see the Dependencies development guide.

Build docs developers (and LLMs) love

Get started for freeTalk to us