Skip to content

Troubleshooting

Solver unavailable

Symptom: the Solver panel reads PyRoki unavailable, with an error line underneath and Using NumPy fallback.

What it means: the full solver stack failed to import. Kinema still works — IK is being solved by the simpler NumPy backend — but you have lost the singularity- and limit-aware solving that is the reason to use Kinema.

Diagnose it. The error line is the actual Python import failure. Read it. Then open Edit → Preferences → Add-ons → Kinema for the full dependency report: nine components, each ok with a version or missing with the reason.

Cause 1: the wrong build for your platform

By far the most common. Kinema bundles a compiled maths library, so each platform gets its own zip. Installing the Linux zip on Windows, or an Intel build on Apple Silicon, produces exactly this failure.

Errors that point here mention jaxlib, jax, or a version mismatch between them:

RuntimeError: jaxlib is version 0.7.0, but this version of jax
requires version >= 0.11.1.

Fix: remove the extension, download the zip matching your OS from the releases page, and install that. See Install.

Cause 2: a partial install

On Windows, an install interrupted by the long-path limit leaves some components on disk and some missing. The report will show missing against several entries at once.

Fix: enable long paths, remove the extension, and reinstall.

Cause 3: it has not been loaded yet

The solver stack is imported the first time something needs it, not at startup, so a fresh Blender session reports nothing until you ask for a solve.

Fix: click Re-check, which imports it. Expect a 2–5 second pause the first time.

Still stuck?

Click Re-check first — it re-runs the whole dependency check. If the report still shows failures, that screenshot plus the error line is exactly what to put in a bug report.

Windows: WinError 206

Symptom: installing the extension fails partway through, with WinError 206 or a message about a path being too long.

Cause: the bundled solver unpacks into deeply nested directories — paths like jax/_src/internal_test_util/export_back_compat_test_data/…. Windows limits paths to 260 characters unless long-path support is switched on.

Fix, either one:

  • Enable long paths system-wide. Set this registry value to 1:

    HKLM\SYSTEM\CurrentControlSet\Control\FileSystem\LongPathsEnabled

    Then restart, remove any partial install, and reinstall the extension.

  • Or keep Blender's configuration directory shallow — a path near the root of a drive rather than nested inside several folders of user data.

Blender freezes for about 15 seconds

Symptom: clicking Add IK Target locks Blender up, with a wait cursor.

This is expected, once per robot. The solver compiles itself for this specific robot's structure the first time it runs. Kinema pays that cost deliberately at the moment you add the target, rather than letting it land on your first drag of the control.

Subsequent solves take milliseconds. Loading a different robot compiles again. Changing the tool offset, or removing the IK target and adding it back, does not.

See why the first solve is slow.

The IK panel says PyRoki waits until the edit is done

Not a problem. You made an edit the solver needs compiling again for: an external axis added or removed, or the TCP moved to another joint. Compiling on every adjustment of that edit would freeze Blender each time, so live IK uses the simpler NumPy solver until you are done. It compiles once, when you move on to something else or leave the edit alone for ten seconds. Bakes and renders never wait: they compile first if they must.

Over budget; live updates paused

Symptom: the IK panel shows a warning and the rig stops following the target.

Cause: a solve took longer than the solve budget (33 ms by default), so live updates paused to keep the viewport usable.

Fix, in order of preference:

  1. Raise Solve Budget in Preferences
  2. Switch the rig's Solver to NumPy — faster, less robust
  3. Keep working with live updates off and bake at the end; baking ignores the budget entirely

Very high-DoF rigs — a fifty-joint humanoid — hit this legitimately. A six-jointed arm should not, and if it does, check whether PyRoki is actually loaded.

The robot imported but I cannot see it

Cause: the meshes did not resolve. The rig is correct — joints, limits and IK all work — but there is no visible geometry.

URDF files reference meshes by path, usually with a package:// URL. Kinema resolves these by searching the description file's own directory tree, which needs the tree to be there.

Fix: make sure you have the whole robot package, not just the .urdf file. The meshes/ folder must be present alongside it. Downloading a single description file from a repository web page is the usual mistake.

The parts pile up at the origin, then snap into place

Not a bug. Meshes are loaded one at a time and parented to their bones before any of them is positioned, so for a moment the robot is a heap at the world origin. It resolves itself on the next redraw.

Blender freezes while a robot imports

Not a bug, as of 0.3.0. An import blocks: Blender puts up a wait cursor and stops responding until the rig is built. A second or two for an arm, longer for a humanoid, where most of the time goes on one mesh-importer call per visual.

It used to run in the background with a progress bar and Esc to cancel, which meant a worker thread — and Blender extensions may not start threads. There is no cancel any more; if you picked the wrong file, wait for it to finish and undo.

There are fewer bones than I expected

Not a bug. Two bone collections are hidden on a new rig:

  • Kinema/IK — until you add an IK target
  • Kinema/Mechanism — internal bones that are not controls

Unhide them in the Properties editor under Object Data → Bone Collections. See bone collections.

Also worth knowing: in a robot rig, bones are joints, not limbs. A six-jointed arm has six control bones, not one per visible segment.

Move TCP to Active Bone raises an AttributeError

Symptom: on 0.1.0 only, clicking Move TCP to Active Bone (or Create TCP from Active Bone) prints a traceback ending in:

AttributeError: 'Bone' object has no attribute 'select'

Cause: the button acted on the bone that was active in Pose Mode, and did not cope with there being none. A freshly imported robot has no bone selected, so clicking it straight after an import hit this every time.

Fix: update to 0.2.0, where the TCP's bone is chosen from a Parent Bone field in the panel and no mode change is needed. On 0.1.0, enter Pose Mode and click a bone first.

Symptom: part of the robot is floating off on its own, or rotated, and Rest Pose does not bring it back.

Cause: the robot's visual meshes are separate objects parented to the bones. Grabbing one by accident moves it, and Rest Pose returns the joints — a mesh is not a joint, so it stays where it was left.

Fix: Reset Meshes, in the Joints (FK) panel beside Rest Pose. It puts every link mesh back where the importer placed it, and leaves anything you attached yourself alone.

From 0.2.0 the meshes are also locked, so this is harder to do by accident. A rig imported with 0.1.0 has no record of where its meshes belong and cannot be repaired — re-import it.

The robot will not go to its rest pose

Symptom: on import, a warning naming a joint and its limits — and Rest Pose leaves the robot slightly off the pose the description seems to describe. On a KUKA quantec the arm sits about 5° up from horizontal.

Cause: not a fault. The description's zero configuration is outside that joint's own limits, because the real axis cannot reach it. Every KUKA quantec is like this — kr120, kr150, the kr210 family, kr240, kr300, kr340, kr500 all limit the second axis to a range stopping short of zero.

Kinema keeps the rig's rest pose at the description's zero, because the whole rig and the solver are built on that being true, and then the limit constraint moves the robot to the nearest value it is allowed. That is the honest answer: the robot genuinely cannot stand where a naive reading of the file says.

Fix: nothing to fix, usually. If you want to see the description's own zero pose, re-import with Enforce Joint Limits off — accepting that you are then free to pose the robot where the real machine cannot go.

Fixed in 0.4.0

Before 0.4.0 this produced a real fault as well: the bones moved to the allowed value but the meshes stayed behind, so the robot's geometry and its skeleton disagreed by up to 0.22 m at the flange. Re-import any rig imported before 0.4.0 from one of these robots.

A collision mesh is showing over the robot

Symptom: coarse boxes and cylinders drawn as wireframe, roughly robot-shaped, sitting over or inside the visual geometry.

Cause: you imported with Import Collision Meshes on, and unhidden the collection. These are the hulls a motion planner sweeps, not what the robot looks like.

Fix: hide the ⟨robot⟩ Collision collection in the outliner — click its eye. It starts hidden; something un-hid it. To be rid of them entirely, re-import with the option off.

Add IK Target is refused

Symptom: "This rig has no TCP; create one first".

Cause: the IK target is created at the tool centre point, so there has to be one. This happens if you imported with Create TCP turned off.

Fix: enter Pose Mode, select the bone at the end of the chain, and click Create TCP from Active Bone in the Tool Centre Point panel.

The arm stops short of the target

Cause: the target is unreachable — outside the robot's workspace, or blocked by a joint limit. The solve does not converge and the panel says so.

Fix: move the target inside the robot's reach, or move the rig's root bone to bring the robot closer. If you believe the limits are wrong, you can re-import with Enforce Joint Limits off — but then you are animating poses the real machine cannot achieve.

See reach.

Starting from a fully stretched arm

There is one known case where a reachable target doesn't converge: an arm that starts straight out, like a UR at its rest pose. A small target move from there can stop a fraction of a millimetre and about half a degree short, and stay there. Bend the arm first, with a few FK sliders, and the same target solves exactly. Tracked in #56.

A joint shows — in Velocity Limits

Cause: live IK drives that joint, and you jumped to this frame. Kinema measures such a joint against where the solver put it one frame earlier. After a jump or a scrub it hasn't seen that frame, so it has nothing to compare against. A keyed joint never shows this: its own curve says where it was.

Fix: step a frame, or play. The speed appears as soon as Kinema has seen the frame before. See how a speed is measured.

The tool offset is not zero on the flange

Cause: the rig was imported before 0.6.0, or the robot description defines no mounting flange (tool0 or flange). Either way the offset is measured from the last joint's link frame, which on many robots sits inside the wrist. The Tool Offset section says which frame it is measured from.

Fix: import the robot again to measure from the flange. Nothing needs fixing on an old rig, though: its offsets keep the meaning they were typed with. See where zero is.

The IK target and the robot disagree

Cause: they have drifted apart — you posed the arm with FK while the solver was Off, or a solve failed to converge.

Fix: Snap to Tool, which puts the target back on the tool.

MTL errors in the console

Symptom: importing an MJCF robot prints errors about missing .mtl files.

Harmless. MuJoCo robots often ship OBJ meshes without their material companion files, and Blender's OBJ importer complains. MJCF carries its own colours, so nothing is actually missing. Ignore it.

A robot will not import at all

Ball joints are rejected. A 3-DoF spherical joint has no honest single-axis bone equivalent. Exactly one catalog robot — Cassie — is affected.

A xacro is missing a required argument. The error names the argument and lists the others the file declares. Select the file in the browser first and Kinema shows the same list with defaults, before you import. Fill in the Xacro Arguments field — name:=ur5e ur_type:=ur5e — and try again. See xacro arguments.

A package it refers to cannot be found. A xacro reaches other packages by name, and Kinema looks inside the checkout holding the file you picked. If the pieces live in separate clones side by side, add the directory above them to Package Search Paths.

Note that a package is identified by the name it declares in its package.xml, not by its folder name — Universal_Robots_ROS2_Description declares itself ur_description, and a description referring to it that way is correct.

Or it is not a robot description at all. Kinema reads URDF, xacro and MJCF.

The catalog does not import anything

Not a bug, as of 0.3.0. The catalog is a directory, not a downloader. Picking a robot copies a git clone command to your clipboard and names the file to open; you run the clone and then load that file with Import URDF File….

If the clone itself fails, the repository has usually moved since the Kinema release you have — the catalog is a snapshot of URLs and pinned commits. Search for the project by name, or open an issue so the entry gets fixed.

See Robot catalog.

The baked animation looks wrong

Cause: frames where the solve did not converge. Kinema reports the count of failed frames when the bake finishes.

Fix: go to those frames, move the IK target into reach, and bake again.

If the motion is wrong specifically between keys, you may have baked with Step above 1. Interpolating between two solved poses does not always follow a path the robot can take. Bake every frame.

Reporting a bug

Please include:

  1. Your OS and which zip you installed
  2. Your Blender version
  3. A screenshot of the dependency report in Preferences
  4. The robot involved — catalog name, or the format if it is your own file
  5. Console output with Debug Logging enabled (how to open the console)

Open an issue.