Troubleshooting

This page covers common issues and their solutions.

Connection Issues

Error: “Robot is not ready”

Symptoms:

Connecting with aiofranka.Robot(ip) fails, or, in the legacy server mode, controller.start() prints a status summary and exits:

Joints ........... locked
FCI .............. inactive

Robot is not ready. Unlock first:

Solution:

Unlock the robot before connecting:

import aiofranka

aiofranka.unlock()                       # unlock joints + activate FCI
robot = aiofranka.Robot("172.16.0.2")    # now this connects

Or from the CLI:

aiofranka unlock

Cannot Connect to Robot

Symptoms:

ConnectionError: Unable to connect to robot

Diagnosis:

# Test network connection
ping 172.16.0.2

# Should show < 1ms latency

Solutions:

  1. Check physical connection — Ethernet cable connected? LED on robot’s network port lit?

  2. Check IP configuration — Correct IP? Subnet mask correct (typically 255.255.255.0)?

  3. Check firewall

    sudo ufw allow from 172.16.0.0/24

  4. Check robot state — Robot powered on? No error lights? Can you access Franka Desk GUI in browser?

Server Not Responding

Symptoms:

ConnectionError: Server not responding (timeout). Check if server is running.

Solutions:

  1. Check if the server subprocess is still alive:

    print(controller.running)  # True if server is responsive

  2. Check server logs:

    aiofranka log -n 50

  3. The server may have crashed due to a control loop error. Check for error messages:

    # This will raise RuntimeError with the error message if server errored
state = controller.state

Robot Behavior Issues

Robot Triggers Safety Stop

Symptoms: Robot suddenly stops moving, yellow lights flash.

Common Causes:

  1. Torque Rate Too High — Lower gains or ensure smooth commands:

    controller.kp = np.ones(7) * 40.0   # Lower stiffness
controller.kd = np.ones(7) * 6.0    # More damping

  2. Discontinuous Commands — Use smooth trajectories:

    # Bad: jump to far target
controller.set("q_desired", far_target)

# Good: use trajectory generation
controller.move(far_target)

  3. Collision Detected — Clear workspace, check for obstacles

  4. Communication Constraints Violation — Torque commands reached the robot late, e.g. a blocking call starved the legacy FrankaController’s loop. See Communication Constraints Violation below.

Recovery:

# Recover safety errors and re-unlock
aiofranka unlock

Jerky or Oscillating Motion

Causes & Solutions:

  1. No Rate Limiting:

    # Always set frequency before control loop
controller.set_freq(50)

  2. Low Damping:

    controller.kd = np.ones(7) * 6.0

  3. High Gains:

    controller.kp = np.ones(7) * 40.0  # Try lower

  4. Discontinuous Targets — Use smooth functions:

    delta = np.sin(cnt / 50.0 * np.pi) * 0.1

Robot Doesn’t Move

Diagnosis:

print(f"Running: {controller.running}")
state = controller.state
print(f"Current position: {state['qpos']}")
print(f"Desired position: {controller.q_desired}")
diff = np.linalg.norm(controller.q_desired - state['qpos'])
print(f"Distance to target: {diff}")

Common Issues:

  1. Forgot to call start() — controller.start() must be called first

  2. Wrong controller type — Sending q_desired but in OSC mode? Use controller.switch("impedance")

  3. Target equals current — Check the distance to target

  4. Gains too low — Increase kp

Control Loop Issues

Communication Constraints Violation

Symptoms: Robot aborts motion with communication_constraints_violation error.

Cause: Torque commands reached the robot late. With the legacy Python loop (FrankaController, aiofranka start-server --python), a blocking call in your code starved it. The native loop does not wait for Python, so with it the cause is the system: a saturated CPU, the network, or a loop thread without real-time priority.

Solutions:

  • Use the native loop: Controller, or NativeFrankaController in asyncio code

  • With the legacy FrankaController, follow the Async Mode Guide guide to avoid blocking the event loop

  • With the native loop, use wired Ethernet, keep a core free for the robot NIC’s interrupts, and give the loop’s thread its SCHED_FIFO priority (see Native Control Loop). aiofranka rt-benchmark measures the loop (see CLI Reference).

Low Control Frequency

Symptoms: test_connection() shows frequency < 990 Hz or high jitter.

Solutions:

  • Use a wired Ethernet connection (not WiFi)

  • Reduce system load (close unnecessary programs)

  • Consider a real-time Linux kernel

  • Run aiofranka rt-benchmark to measure the loop on this machine

OSC Issues

OSC Unstable or Oscillates

Causes:

  1. Near singularity:

    jac = controller.state['jac']
cond = np.linalg.cond(jac)
if cond > 100:
    print(f"Warning: Poor conditioning: {cond}")

  2. Gains too high:

    controller.ee_kp = np.array([200, 200, 200, 600, 600, 600])
controller.ee_kd = np.ones(6) * 8.0

  3. Null-space conflict:

    controller.null_kp = np.ones(7) * 5.0
controller.null_kd = np.ones(7) * 1.0

OSC Doesn’t Reach Target

Diagnosis:

state = controller.state
ee_current = state['ee']
ee_desired = controller.ee_desired

pos_error = np.linalg.norm(ee_desired[:3, 3] - ee_current[:3, 3])
print(f"Position error: {pos_error * 1000:.1f} mm")

Causes:

  1. Target unreachable (outside workspace)

  2. Null-space pulling away — adjust null_kp / null_kd

  3. Singularity — move via intermediate poses

Programming Issues

TypeError: ‘coroutine’ object is not iterable

Cause: Forgot to await an async function.

# Wrong (NativeFrankaController)
controller.start()

# Correct (NativeFrankaController)
await controller.start()

Note

This only applies to NativeFrankaController. Controller’s calls are plain.

RuntimeError: This event loop is already running

Cause: Using asyncio.run() inside an async function.

# Wrong
async def my_function():
    asyncio.run(controller.start())

# Correct
async def my_function():
    await controller.start()

Getting Help

Before asking for help:

  1. Check this guide — is your issue covered?

  2. Test in simulation — does it work with aiofranka.Robot(None)?

  3. Review the examples in Examples

  4. Check server logs: aiofranka log -n 50

  5. Simplify — does a minimal example reproduce the issue?

When asking for help, include:

  1. aiofranka version: pip show aiofranka

  2. Operating system and Python version

  3. Minimal code that reproduces the issue

  4. Full error message from terminal

  5. Which controller you use: Controller, NativeFrankaController, or a legacy one

Where to ask: