Troubleshooting

Start with Basic Sample to separate SDK communication from XR setup. Record the package revision, Unity version, input backend, host settings and diagnostic values when investigating a problem. Do not include credentials in logs or support reports.

Package does not install or compileCopy Anchor Link

• Check the package ID and path in Setup.
• For a Git installation, confirm Unity can run Git and access the repository. A repository permission error is not an SDK runtime failure.
• For a disk installation, select Packages/com.melt-interface-technologies.contactglove.sdkv2/package.json.
• Resolve the first Console error before importing more packages. The core declares Unity UI, Physics, IMGUI and ImageConversion; OpenXR/XR Hands for VR, and Input System when needed, are installed separately in the project.

Connect returns TransportUnavailableCopy Anchor Link

In Basic Sample, the status shows Host unavailable and the Console logs a TransportUnavailable warning. Another process or session may already own the requested receive/send port. Check the result detail and LastError. Stop the conflicting instance or choose distinct local ports. ReceivePort=0 and SendPort=0 request available ports; inspect the actual allocated values after startup.

Several Editor/Player instances using the same fixed receive port cannot share that socket. Do not confuse DivingStation's ServerPort with the SDK's local ReceivePort.

Status remains WaitingForDataCopy Anchor Link

1. Verify that the required DivingStation version is running and that the glove is connected and enabled there.
2. Confirm IpAddress and ServerPort; use 127.0.0.1 only when both applications are on the same computer.
3. Check Protocol v2 in DivingStation. Open Settings > SDK / Protocol from the gear icon in the upper-right corner and look at SDK status under SDK / DivingStationProtocol v2.
   • If it does not show Active, the registration from Unity has not reached DivingStation or has not been approved yet. Check steps 2 and 4. If DivingStation cannot listen on its port, it shows "SDK / Protocol listener could not start".
   • If it shows Active but no data arrives, check that External Output > SDK does not show "The SDK is a ContactGlove3 Pro-only feature." While it is shown, no data is delivered.
4. On a LAN, check the LAN connection settings. If you changed Listening scope to Expose on LAN in DivingStation's SDK / Protocol, restart DivingStation. If the connection policy requires approval, allow the pending connection request. Check that the required UDP traffic is allowed on the actual receive ports of both PCs.
5. Check diagnostics. Increasing UnexpectedSources suggests packets from an IP other than the configured host; increasing ParseErrors suggests rejected packets.
6. Retry registration on the retained client with Resume or matching Connect settings. Do not repeatedly stop/start while waiting for approval.

WaitingForData alone cannot distinguish approval waiting, network loss, server absence or no published data. Local Connect success is not an approval acknowledgement. Keep network access limited to the trusted environment you intend to use.

InvalidArgument when retrying ConnectCopy Anchor Link

The existing HostId may refer to a different endpoint or different configured ports. Retry with the original settings, including 0 for any originally automatic port. To deliberately change the connection, disconnect that host and create a new session. Changes to an Inspector field do not mutate the running copy of HostOptions.

A connected glove is not selectedCopy Anchor Link

Check the sample's HostId and per-side IDs. Auto is deliberately unavailable when more than one connected device of that side exists. Choose an explicit ID. A previously selected disconnected ID remains selected so that the application cannot silently act on another glove.

Check each stream independently. Metadata arrival and Connected do not guarantee that Controller, Ergonomics or Skeleton data has arrived. Use GetDataStatus and AgeSeconds.

Skeleton or angle panels are blankCopy Anchor Link

Check the selected device, selected raw/retargeted stream and freshness. Stale or unavailable frames are hidden by the sample. The sample uses a 0.5-second freshness threshold by default; this is a demo policy and can be adjusted deliberately.

An IK-failure frame can be displayed for diagnosis, but it must not drive application control. Raw and retargeted skeletons can have different states. A profile-information timeout does not itself prevent skeleton display.

Skeleton position or orientation looks wrongCopy Anchor Link

With Basic Sample's SkeletonRenderer, pass the received snapshot directly to Apply. For your own visualization, use UnityPoseConverter to convert received values to Unity coordinates once.

Positions are in meters relative to the wrist. Check the display root's position, rotation and Scale, and how you place the joints. Joints under one display root and joints in a bone hierarchy require different localPosition values. The 19 rotations are relative to parent joints. See Coordinates and Unity visualization for the conversion and placement instructions.

F/J or UI buttons do not respondCopy Anchor Link

• Focus the Game view or Player window.
• Confirm a single connected glove is selected for that side.
• The on-screen vibration button requires the device's vibration capability.
• Under New-input-only, make sure Input System is installed and the active EventSystem uses its UI module. The sample preserves existing UI action bindings and does not change Active Input Handling.
• Inspect the result text and Console for command rejection.

Vibration reports Success but nothing is feltCopy Anchor Link

Success confirms local submission only. Check the glove's connection/capability, the chosen ID, DivingStation's client approval and physical device state. Use the specified frequency, amplitude and duration ranges. The SDK has no actuation acknowledgement and does not replay a command when communication returns.

Profile query times out or returns NotFoundCopy Anchor Link

Use the actual ProfileUuid from a retargeted skeleton. NotFound is a server response; timeout means the local deadline elapsed without a correlated response. They are different outcomes. Check communication and approval, and inspect unmatched-response diagnostics if needed. Skeleton delivery and rendering do not require the profile's display name.

Callbacks stop or notifications are lostCopy Anchor Link

For an owned client, call PumpNotifications from one thread each frame. Do not add a second pump when using ContactGloveBehaviour. Keep subscription tokens alive and resubscribe after an explicit disconnect/new client.

Watch queue depth, notification drops and callback exceptions. Release latched input after SubscribeNotificationLoss, then establish a fresh baseline. Increasing capacity can absorb a burst, but does not fix an owner that never pumps. UDP delivery cannot guarantee every input transition.

HandVisualizer does not display handsCopy Anchor Link

1. Check that you are using OpenXR 1.17.1, XR Hands 1.8.1 and the official HandVisualizer.
2. Verify OpenXR and the Hand Tracking feature are enabled. Enabling them only under Android does not configure PC. Check Project Validation and the first Console error.
3. Check the PC’s active OpenXR runtime and Unity’s Play Mode OpenXR Runtime. For SteamVR, confirm the runtime is running and recognizes the HMD and tracking devices.
4. Check the render pipeline. With Unity's Built-in Render Pipeline, hands have sometimes required additional settings, such as forcing DirectX 11, to appear. We recommend Universal Render Pipeline (URP).
5. Inspect Unity’s OpenXR diagnostic log for the actual runtime, extensions and features. Hand data requires XR_EXT_hand_tracking. Successful controller-pose tracking does not establish that hand joints are available.
6. If third-party OpenXR API layers are installed, record their names, versions and errors. Follow the provider’s management instructions to compare behavior with and without an added layer. Do not bulk-delete registry entries or bypass security warnings. Record the original configuration so the diagnostic change can be reversed.
7. For incorrect placement, check XR Origin, the tracking origin and mounting offsets. Check the SDK and XR Hands joint mappings. Use XR Hands poses directly, since they are in Unity coordinates.

Change one setting at a time when investigating a cause. Record the graphics API, Render Pipeline, Render Mode and predicted-time setting to compare results.

Windows Player build failsCopy Anchor Link

Select Windows in File > Build Profiles and check the scenes included in the build. Start with the first Console or build-log error. Install the Windows build module. If you choose IL2CPP, also provide the matching Unity module and C++ build environment.

After building, run on the target PC and check DivingStation communication, input and body vibration. For VR, prepare the OpenXR runtime and HMD, then also check HandVisualizer rendering.