When the steps in a section do not help, reproduce the problem once with the Debug logs turned on, then provide that run's logs together with the terminal output to our technical support.

Cannot install the SDK or an algorithm package

Check that the Python version and platform are supported and that pip install qnbot-sdk-glove finishes without errors; for the full requirements, see Installation & requirements.

Check that the algorithm package is installed before the Sdk is created: qnbot algorithm list shows the target package and its ID matches TargetAlgorithm. See Package management for install, upgrade and removal.

What to do: recreate the Sdk after installing the package; a running instance does not pick up package changes. If it still fails, attach the install command and the error to the Debug logs, see Debug logs.

Cannot find the device

Check: run discover_gloves() to see the candidate ports, hand sides and device identities; in an already created SDK, read connected and last_error from device.status().

• No candidates: check the USB connection and serial port permissions, then try another port.
• More than one candidate: select one with SerialConnection(port=...) or serial_number=..., or give the glove a name / side.
• glove.device() raises AmbiguousSelectionError: an unconditional selection must yield a unique device; when multiple candidates exist, use device(name="...") or device(side=Side.LEFT) to select explicitly.

For the full configuration, see Device discovery & connection.

Connected but no data

Check: is connected true and stale stuck at true in device.status(); does pose().latest() return None.

• latest() returning None is not an error: it is a non-blocking query and means the data has not arrived yet. To wait for data, use a callback, await device.pose().next() or async for sample in device.pose().
• Raw data: make sure subscribe() was registered before start(), or wait after startup with next() / async for; calling latest() once does not wait.
• SDK-processed data: choose a runtime mode and keep it advancing; the target needs an installed algorithm package, see Reading retargeting data.

If data still does not arrive, read last_error and stale in Device status and diagnostics and turn on the Debug logs in Debug logs.

Calibration did not pass

Check: does device.calibration_status() still ask for calibration; which stage is capture_progress() stuck at; which guided motion failed in the terminal.

• Retry the failed motion; resample with CaptureConfig(force=True), or recompute only the calibration with CalibrationConfig(force=True) — the two mean different things.
• In an external-takeover flow, use capture_control() and the matching session calls to confirm, skip, retry or cancel, see Capture.

If it still fails, keep the capture and calibration modules in the Debug logs and report them with the terminal output.

Data is late or the output stops updating

Check: runtime_overrun and topic_callback_error in glove.health(); is SDK scheduling still advancing.

• Processed data depends on the runtime: keep calling update(), or keep run_forever() / run_background() running; waiting for output without advancing the schedule never produces new data, see Runtime modes.
• Do not do time-consuming work in a callback: the SDK runs callbacks in sequence, and slow callbacks delay later data processing. Put the data into a business queue and process it on a worker thread.
• Mixing runtime modes in the same run raises LifecycleError; pick one.

Does Glove represent only one glove?

No. Glove manages every configured glove; each GloveDevice represents one physical glove within it.

Can one glove drive multiple dexterous hands at the same time?

Yes. Configure multiple targets for the same source, then read each output through device.output(name=...). There is still only one glove connection and one input data stream.

Why does data reading not use poll_pose() or on_output()?

Read the data you need directly through pose(), output() or status(), then call latest(), subscribe(), await next() or use async for as needed.

Why is there no set_haptics()?

After calling device.haptics(), use set() to set the vibration strength of each finger and clear() to stop the vibration.

What happens if a callback raises an unhandled exception?

It does not terminate the SDK, and later data keeps being processed. To see the exception, catch and log it inside the callback.

Can update() and run_background() be called at the same time?

No. Manual, current-thread and background are mutually exclusive runtime models. Enabling them together raises LifecycleError.