Skip to main content

Troubleshooting

Save guest work before restarting or changing its configuration. Keep the Transit version/build, macOS version, Mac model and your reproduction steps when reporting a problem.

Download will not finish​

  • Read the create sheet's error instead of repeatedly starting new downloads.
  • Check the Mac's internet connection and enough space for download, unpacking and the writable VM disk.
  • If an external storage location is selected, reconnect that drive or choose an available location in Settings > Storage.
  • Keep the create sheet open while downloading; closing it cancels its active transfers.
  • Retry after resolving the reported issue.

Transit checks signed download information and downloaded files. An invalid or expired catalog or mismatched download cannot be bypassed from the user interface. Report the exact message if retrying does not help.

The VM cannot start​

  1. Stop another running or paused VM; only one can occupy the running slot.
  2. Check that the VM's drive and any selected boot files are available.
  3. Read any resource, file-access or subscription message.
  4. Open More (…) > Serial Console for boot details.

For a custom image, retry with a curated Ubuntu VM to distinguish custom boot compatibility from an app problem. Avoid editing or deleting the managed disk as a recovery step.

Black screen or missing windows​

First check whether the VM is Paused and use Resume if needed. Allow the initial desktop boot to finish, and open Serial Console to see whether the guest is still producing output. If a dialog is missing, report the application and exact action that opened it, such as LibreOffice's Save dialog.

If the guest terminal still works, save what you can and shut down normally. Use the guest power menu, or sudo systemctl poweroff from a logged-in serial/SSH terminal. Restart only after Transit reports Stopped. Force Stop is a last resort because it can lose guest writes.

Do not disable GPU acceleration as a permanent workaround for a desktop rendering problem. Send the reproduction steps and local diagnostics so the supported GPU path can be investigated.

Fullscreen or resizing stops responding​

Release captured input with Esc, then try View > Exit Full Screen from the Mac menu bar. If the normal window returns, keep the guest's working display mode and save work. Record whether the problem followed a window drag, resolution change, fullscreen entry/exit or movement to another desktop.

Native fullscreen and resize improvements are still being qualified in development. A successful fullscreen transition once does not rule out an intermittent stall. Include how long the session had been running and whether the guest or only the Mac window stopped responding.

Higher resolutions are unavailable​

The Mac window size and Ubuntu's display resolution are separate. Fit Window to Guest changes the Mac window only. Choose only the resolutions available under Ubuntu Settings > Displays. Do not expect resizing the Mac window to add modes or automatically change the guest. The explicit guest-resolution toolbar action is still being qualified.

Keyboard or pointer goes to the wrong place​

  • Click the Ubuntu desktop before typing in it.
  • Click the Serial Console command field before sending console commands.
  • Press Esc to leave captured-cursor mode.
  • Use Linux Control shortcuts inside guest apps; Mac Command shortcuts belong to the Mac app.
  • Report the guest resolution and window/fullscreen state if clicks are offset.

Clipboard sharing and cross-boundary file dragging are not implemented. Use the shared folder rather than troubleshooting them as broken features.

Shared folder or external drive is unavailable​

Stop the VM, reconnect the drive, then choose the shared folder or boot file again in configuration if required. A storage-location change does not move existing VMs. The VM continues to need the drive where its existing files live. See files and storage.

Shutdown keeps waiting​

Ubuntu may display its own power-off confirmation inside the VM. Confirm that dialog or use Ubuntu's power menu. From a logged-in terminal, sudo systemctl poweroff requests normal shutdown. Wait for Stopped before unplugging the drive. Force Stop can discard unsaved work and should be reserved for an unresponsive guest.

Subscription is not recognized​

Use the Apple Account that purchased Transit Annual and choose Restore Purchases in Start using Transit or Transit > Settings > Access. If purchases cannot be verified, check the Mac's connection and use Check Again or Restore Purchases in Access settings. Keep the current library and VM files while resolving access; starting a VM still requires verified access. Subscription instructions explain trial eligibility and TestFlight access.

Export diagnostics for support​

Choose More (…) > Export Diagnostics… for the current VM, or Settings > Storage > Export Diagnostics for the app's VMs. Choose a local file in the Save dialog. Transit does not send it automatically.

The export contains logs and configuration, not saved passwords. Logs can still contain VM names, local paths or text produced by guest programs. Read the file and remove anything you do not want to share before emailing it. Screenshots can also contain private documents; review them before attaching them.

Send the relevant file and steps to feedback@yooz.live. Mention whether you use an App Store or TestFlight build.