English · Русский

English

What this project addresses

OculusQuestLink-Fix is a one-click Windows workaround for a wired Meta Quest Link failure with this pattern:

• wired Link starts normally, then freezes or disconnects;
• subsequent attempts fail until OVRService is restarted;
• starting Link while the PC is temporarily offline makes the session stable;
• Ethernet must be turned back on after Link has initialized.

The primary shortcut reproduces the useful part of the offline startup without disconnecting the whole PC: by default it temporarily blocks outbound network access only for OculusDash.exe, restarts OVRService, launches Meta Horizon Link, waits for Dash, and restores access 25 seconds later. A fallback shortcut can automatically toggle the detected physical network adapter instead.

Important

This is an unofficial community workaround. It is not affiliated with or endorsed by Meta. It does not modify headset firmware or Meta application binaries.

Quick start

1. Download OculusQuestLink-Fix-v1.0.1.zip from Releases.
2. Extract the ZIP. Do not run the installer from inside the archive.
3. Double-click Install.cmd and approve UAC.
4. Connect the headset by USB, click Quest Link Safe Start, then enable Quest Link in the headset within 10 minutes.

Optional integrity check after downloading the release assets:

(Get-FileHash .\OculusQuestLink-Fix-v1.0.1.zip -Algorithm SHA256).Hash.ToLower()
Get-Content .\SHA256SUMS.txt

Ethernet remains enabled in the primary mode. Browsers, Steam, downloads, and other applications keep their network access.

The three shortcuts

Shortcut	What it does	When to use it
Quest Link Safe Start	Temporarily isolates OculusDash, restarts OVRService, launches Meta Horizon Link, and restores Meta network access after Dash + 25 seconds.	Use this first. The PC stays online.
Quest Link Safe Start - Network Fallback	Temporarily disables the detected physical Ethernet/network adapter and automatically enables it again after Dash + 25 seconds.	Use when process-only isolation does not help.
Restore Quest Link Network	Immediately disables this project's temporary firewall rules and re-enables an adapter only if this tool recorded that it disabled it.	Use after an interrupted or forced shutdown.

If OculusDash is already running in the current Windows session, Safe Start preserves that session and does not restart it.

flowchart LR
    A[Click Safe Start] --> B[Write recovery marker]
    B --> C[Arm recovery watchdog]
    C --> D[Temporary Dash isolation]
    D --> E[Restart OVRService]
    E --> F[Launch Meta app; user enables wired Link]
    F --> G{OculusDash detected?}
    G -->|Yes| H[Wait 25 seconds]
    G -->|10-minute timeout| I[Return a timeout error]
    H --> J[Restore network]
    I --> J

Loading

Why network recovery is safer

Network access is restored after normal completion, a timeout, and handled errors. Before changing anything, the tool writes an atomic recovery marker and arms an independent one-time Scheduled Task. A second recovery task runs at Windows logon. This covers most forced termination, restart, and power-loss cases. The manual recovery shortcut is also always available.

The elevated Scheduled Tasks execute scripts only from %ProgramFiles%\OculusQuestLink-Fix, where standard user processes cannot replace them. Configuration and logs are kept under a restricted %ProgramData%\OculusQuestLink-Fix directory.

Installation options

The installer automatically discovers Meta Horizon Link through the Oculus registry key. It prefers a physical 802.3 adapter on the default IPv4 route, then another active physical wired adapter, and finally a physical default-route adapter such as Wi-Fi. Custom selections are supported:

powershell -ExecutionPolicy Bypass -File .\src\Install.ps1 `
  -MetaBasePath "D:\Meta Horizon" `
  -NetworkAdapterName "Ethernet 2"

Useful options:

• -IsolationScope DashOnly — default and least invasive;
• -IsolationScope AllMeta — temporarily isolate Dash, OVRServer, OculusClient, and Platform Runtime;
• -OnlineRestoreDelaySeconds 25 — delay after Dash appears;
• -DashTimeoutSeconds 600 — maximum time to enable Link in the headset;
• -NoDesktopShortcuts — create Start Menu shortcuts only;
• -DryRun — read-only environment validation.

Re-running a newer installer updates the existing installation and refreshes the detected paths.

USB “device descriptor request failed” warnings

An unknown USB warning can be separate from a working Quest connection. Run Diagnose.cmd to list Meta USB interfaces and failing USB nodes without changing the system or uploading anything. A timestamped text report is saved to the Desktop so it can be reviewed or attached to an issue.

USB\VID_0000&PID_0002 is a placeholder created when Windows could not read the real device descriptor. It does not identify Quest, a vendor, or a driver. The actual fix is to identify the physical device or port: disconnect other USB devices one at a time, move the device to another port, inspect front-panel/internal USB headers, and replace faulty hardware if the warning follows it. See USB troubleshooting.

This installer intentionally does not disable an unknown USB instance automatically. Instance IDs are unique to one PC, and disabling a node only suppresses it; it does not repair a descriptor failure.

Troubleshooting

• The primary shortcut still disconnects: try the Network Fallback shortcut. It will turn the adapter back on automatically.
• Nothing happens: close a stale OculusDash.exe, or restart Windows, then try again.
• The network did not return: click Restore Quest Link Network. The tool never enables an adapter unless its recovery marker says the tool disabled it.
• Meta was installed to a custom folder: re-run the installer with -MetaBasePath.
• The wrong adapter was detected: re-run with -NetworkAdapterName.
• Need logs: open %ProgramData%\OculusQuestLink-Fix\Logs\SafeStart.log or run Quest Link Diagnostics from the Start Menu; diagnostics saves a timestamped report to the Desktop.

More details are in Troubleshooting.

Uninstall

Use Settings → Apps → Installed apps → OculusQuestLink-Fix → Uninstall, the Start Menu uninstall shortcut, or Uninstall.cmd from the release. The uninstaller first restores changes recorded by the tool, then removes its firewall rules, Scheduled Tasks, shortcuts, files, and application entry.

Limitations and security

• Windows 10/11 x64 and Windows PowerShell 5.1 are supported.
• The signed-in Windows account must be a local administrator, and UAC must be approved with the same account.
• The tool targets wired Quest Link, not Air Link.
• It works around a startup path; it cannot repair a defective cable, USB controller, port, or headset.
• Scripts are open source but are not code-signed in v1.0.1. Download release assets only from this repository and verify SHA256SUMS.txt when possible.
• There is no telemetry. The tool does not upload diagnostics or credentials.

Background: Meta previously acknowledged a Quest Link launch issue, and community reports documented offline startup or temporary OculusDash.exe blocking as a workaround: Meta support thread, community workaround.

---

Русский

Какую проблему решает проект

OculusQuestLink-Fix — это автоматизированный обход сбоя проводного Meta Quest Link в Windows со следующими признаками:

• проводной Link запускается, но затем зависает или отключается;
• после обрыва повторное подключение невозможно без перезапуска OVRService;
• если запускать Link при временно отключённом интернете, сеанс работает стабильно;
• после инициализации Link Ethernet необходимо вернуть.

Основной ярлык воспроизводит полезную часть офлайн-запуска без отключения интернета на всём ПК: по умолчанию он временно блокирует исходящую сеть только для OculusDash.exe, перезапускает OVRService, запускает Meta Horizon Link, ждёт Dash и через 25 секунд возвращает доступ. Резервный ярлык умеет автоматически отключить и снова включить обнаруженный физический сетевой адаптер.

Important

Это неофициальное решение сообщества, не связанное с Meta и не одобренное ею. Оно не изменяет прошивку гарнитуры или файлы приложений Meta.

Быстрый старт

1. Скачайте OculusQuestLink-Fix-v1.0.1.zip из раздела Releases.
2. Распакуйте ZIP. Не запускайте установщик прямо внутри архива.
3. Дважды нажмите Install.cmd и подтвердите UAC.
4. Подключите шлем по USB, нажмите Quest Link Safe Start, затем в течение 10 минут включите Quest Link в шлеме.

Дополнительная проверка целостности скачанных файлов:

(Get-FileHash .\OculusQuestLink-Fix-v1.0.1.zip -Algorithm SHA256).Hash.ToLower()
Get-Content .\SHA256SUMS.txt

В основном режиме Ethernet остаётся включённым. Браузер, Steam, загрузки и остальные программы сохраняют доступ к сети.

Три ярлыка

Ярлык	Что делает	Когда использовать
Quest Link Safe Start	Временно изолирует OculusDash, перезапускает OVRService, запускает Meta Horizon Link и возвращает Meta сеть через 25 секунд после появления Dash.	Используйте первым. ПК остаётся онлайн.
Quest Link Safe Start - Network Fallback	Временно отключает обнаруженный физический Ethernet/сетевой адаптер и автоматически включает его через 25 секунд после появления Dash.	Если изоляция одного процесса не помогла.
Restore Quest Link Network	Немедленно отключает временные правила проекта и включает адаптер, только если инструмент записал, что сам его отключил.	После принудительного завершения или сбоя.

Если OculusDash уже работает в текущем сеансе Windows, Safe Start сохраняет этот VR-сеанс и ничего не перезапускает.

flowchart LR
    A[Нажатие Safe Start] --> B[Маркер восстановления]
    B --> C[Аварийная задача]
    C --> D[Временная изоляция Dash]
    D --> E[Перезапуск OVRService]
    E --> F[Запуск Meta; пользователь включает Link]
    F --> G{OculusDash появился?}
    G -->|Да| H[Ожидание 25 секунд]
    G -->|Тайм-аут 10 минут| I[Ошибка тайм-аута]
    H --> J[Восстановление сети]
    I --> J

Loading

Как гарантируется восстановление сети

Сеть возвращается при штатном завершении, тайм-ауте и обработанной ошибке. До любых изменений инструмент атомарно записывает маркер восстановления и создаёт независимую одноразовую задачу. Вторая задача восстановления запускается при входе в Windows. Это покрывает большинство случаев принудительного завершения, перезапуска и отключения питания. Также всегда доступен ручной ярлык восстановления.

Задачи с повышенными правами запускают скрипты только из %ProgramFiles%\OculusQuestLink-Fix, где обычные процессы пользователя не могут их подменить. Настройки и журналы находятся в защищённой папке %ProgramData%\OculusQuestLink-Fix.

Параметры установки

Установщик автоматически находит Meta Horizon Link через реестр Oculus. Сначала он выбирает физический адаптер 802.3 основного IPv4-маршрута, затем другой активный проводной адаптер и, в крайнем случае, физический адаптер основного маршрута, например Wi-Fi. Ручной выбор также поддерживается:

powershell -ExecutionPolicy Bypass -File .\src\Install.ps1 `
  -MetaBasePath "D:\Meta Horizon" `
  -NetworkAdapterName "Ethernet 2"

Полезные параметры:

• -IsolationScope DashOnly — безопасный режим по умолчанию;
• -IsolationScope AllMeta — временная изоляция Dash, OVRServer, OculusClient и Platform Runtime;
• -OnlineRestoreDelaySeconds 25 — задержка после появления Dash;
• -DashTimeoutSeconds 600 — время на включение Link в шлеме;
• -NoDesktopShortcuts — создать ярлыки только в меню «Пуск»;
• -DryRun — только проверить окружение без изменений.

Повторный запуск нового установщика обновляет существующую установку и заново определяет пути.

Ошибка USB «сбой запроса дескриптора устройства»

Предупреждение о неизвестном USB может быть отдельным от рабочего подключения Quest. Запустите Diagnose.cmd: он покажет интерфейсы Meta и проблемные USB-узлы, ничего не изменяя и никуда не отправляя данные. Текстовый отчёт с датой сохраняется на рабочем столе — его можно проверить и приложить к issue.

USB\VID_0000&PID_0002 — это заглушка, которую Windows создаёт, когда не может прочитать настоящий дескриптор. Она не указывает ни на Quest, ни на производителя, ни на конкретный драйвер. Настоящее исправление — определить физическое устройство или разъём: по одному отключить остальные USB-устройства, переставить устройство в другой порт, проверить переднюю панель и внутренние USB-разъёмы, заменить неисправное оборудование, если ошибка следует за ним. Подробнее: диагностика USB.

Установщик намеренно не отключает неизвестное USB-устройство автоматически. Instance ID уникален для каждого ПК, а отключение узла лишь подавляет его, но не ремонтирует сбой дескриптора.

Решение проблем

• Основной ярлык всё равно отключается: используйте Network Fallback. Он сам включит адаптер обратно.
• Ничего не происходит: закройте зависший OculusDash.exe или перезапустите Windows и попробуйте снова.
• Сеть не вернулась: нажмите Restore Quest Link Network. Инструмент не включает адаптер без собственного маркера отключения.
• Meta установлена в нестандартную папку: повторите установку с -MetaBasePath.
• Выбран неправильный адаптер: повторите установку с -NetworkAdapterName.
• Нужны журналы: откройте %ProgramData%\OculusQuestLink-Fix\Logs\SafeStart.log или запустите Quest Link Diagnostics из меню «Пуск» — отчёт сохранится на рабочем столе.

Дополнительные сведения находятся в руководстве по устранению неполадок.

Удаление

Используйте Параметры → Приложения → Установленные приложения → OculusQuestLink-Fix → Удалить, ярлык удаления в меню «Пуск» или Uninstall.cmd из релиза. Деинсталлятор сначала восстанавливает записанные инструментом изменения, затем удаляет его правила, задачи, ярлыки, файлы и запись приложения.

Ограничения и безопасность

• Поддерживаются 64-битные Windows 10/11 и Windows PowerShell 5.1.
• Текущая учётная запись Windows должна быть локальным администратором; UAC необходимо подтвердить этой же учётной записью.
• Инструмент предназначен для проводного Quest Link, а не Air Link.
• Он обходит проблемный путь запуска, но не может починить неисправный кабель, USB-контроллер, порт или шлем.
• Исходный код открыт, но скрипты версии 1.0.1 не имеют цифровой подписи. Скачивайте релизы только из этого репозитория и по возможности проверяйте SHA256SUMS.txt.
• Телеметрии нет. Инструмент не отправляет диагностику или учётные данные.

Контекст: Meta ранее признала проблему запуска Quest Link, а пользователи описали офлайн-запуск или временную блокировку OculusDash.exe как обход: ветка поддержки Meta, обходное решение сообщества.

License / Лицензия

Released under the MIT License. Распространяется по лицензии MIT.