Troubleshooting

Scope

Use this page as the symptom-based index for the knowledge base. Start here when you know the visible problem, but not yet which detailed page to use.

Fast Routing

  1. Check panel for overall status.
  2. Check ethercat command line interface if EtherCAT or slave state is in doubt.
  3. Use the symptom groups below to pick the detailed page.

Startup and EtherCAT

  • EtherCAT validation fails: verify slave order/ids, confirm process image matches hardware, and check for missing power or ESTOP on drives. Use: general, ethercat command line interface, hardware

  • IOC will not start after partial hardware failure: fix cabling and power first; restarting with missing slaves can leave the IOC unusable. Use: general, hardware

  • No slaves are visible or link is down: Use: ethercat command line interface, host / ecmc server, hardware

  • 0x002D: "No Sync Error" and DC slaves remain in SAFEOP + ERROR: A known cause is connecting the incoming EtherCAT cable to the coupler’s downstream/output port instead of its upstream/input port. Slaves may still be detected, but the reversed topology can prevent Distributed Clocks (DC) from synchronizing. The IOC may then fail to start and report:

    Failed to set OP state, slave refused state change (SAFEOP + ERROR).
AL status message 0x002D: "No Sync Error".

    Check the coupler’s port labels or direction arrows: the cable from the controller or preceding slave must enter IN, and OUT must lead to the next slave. Do not assume the direction is correct merely because the link is up or ethercat slaves finds the terminals. After correcting the cable, power-cycle the affected coupler/terminals if necessary, restart the IOC, and verify that the slaves reach OP.

    A reversed coupler connection is one known cause, not the only cause of 0x002D. If the ports are correct, continue by checking the configured DC cycle time, application timing/jitter, link quality, and EtherCAT topology. See also the EL72xx hardware note.

  • Slaves remain in an error state: power-cycle the affected slaves. You can also try ethercat rescan -<master_id>. Always specify the master ID; otherwise, the command rescans every master on the host and may cause error messages in other IOCs.

  • Slaves repeatedly appear and disappear: check for grounding issues. In observed cases, connecting an oscilloscope to measure signals interrupted EtherCAT communication. If possible, use a differential probe and avoid an external ground reference.

Motion and Axis Behavior

  • Axis will not enable: check auto-enable strategy, STO/brake signals, and drive readiness. Use: motion, hardware
  • Axis will not move and reports ERROR_AXIS_HW_NOT_READY: either the drive hardware or the currently selected encoder hardware is reporting that it is not ready. Check the hardware state. For the encoder, also verify that it provides a valid position value. If an open-loop encoder is configured, motion may still be possible by selecting the open-loop encoder as the primary encoder used for control. Use: motion, hardware, YAML encoder settings
  • Axis moves in the wrong direction: Use: direction, motion
  • Homing stalls or never completes: Use: homing, motion
  • Soft limits are not respected: Use: motion, yaml configuration
  • Following error, stall, or poor motion quality: Use: motion, tuning
  • Axis stops close to the target without reaching it: a small position error, combined with a low proportional gain, can become a zero velocity setpoint after output scaling or quantization. Increase Kp, add a small Ki, or reduce the controller deadband tolerance so that position correction remains active near the target. Use: tuning: axis stops close to target, YAML controller settings
  • Encoder raw value differs from the EtherCAT slave value: encoder.bits and encoder.mask apply to the encoder value derived inside ecmc; they do not modify the raw EtherCAT process-data value. Compare with the EtherCAT hardware PV to inspect the original value received from the slave. Use: yaml configuration, scaling

PLC and Scripting

  • Limit logic overrides do not behave as expected: when using plcOverride, verify that PLC code writes ax<id>.mon.lowlim/highlim correctly. Use: motion, PLC configuration
  • Startup scripts or verification scripts behave unexpectedly: review SCRIPTEXEC use and macro expansion. Use: general, Script Reference

Diagnostics Tools

  • Use the RT logger diagnostics to trace motion commands through the motor-record request, ecmc request, and execute stages, inspect blockers, and create a YAML motion-state dump.
  • Use the hardware diagnostics guide for ec_diagnostic_messages.py usage and interpretation: Diagnostics
  • Use read_el70xx_diag.sh or read_el5042_diag.sh for Beckhoff drives/encoders.
  • Check iocsh output for YAML lint/schema errors.

Error Code Quick Map

ErrorTypical cause
ERROR_MON_BOTH_LIMIT_INTERLOCK24V feed for limits missing, cabling issue.
ERROR_MON_MAX_VELOCITY_EXCEEDEDVelocity too high, configuration mismatch, or encoder malfunction.
ERROR_MON_POS_LAG_INTERLOCKFollowing error, motion blocked, configuration mismatch (tolerance too tight).
ERROR_MON_STALLAxis did not reach atTarget after motion finished. Check for motor stall, too-low near-target controller output, unstable mechanics, or too-tight at-target/stall timing. See motion.
ERROR_MON_TOL_OUT_OF_RANGEInvalid monitor tolerance or limit window, for example calculated virtual-axis softlimits outside the valid range. See motion.
ERROR_DRV_HW_ALARM_XHardware error, missing power supply; check dedicated hardware panels.
ERROR_ENC_NOT_READYEncoder issue, cabling issue, or missing power supply.
ERROR_AXIS_HW_NOT_READYThe drive or currently selected encoder hardware is not ready; check its state and verify that the encoder provides a valid position value.
ERROR_EC_LINK_DOWNEtherCAT cabling issue, slave power missing.
ERROR_EC_STATUS_NOT_OKEtherCAT cabling issue, slave power missing.
ERROR_EC_MAIN_DOMAIN_DATA_FAILEDEtherCAT cabling issue, slave power missing.
ERROR_MAIN_ASYN_CREATE_PARAM_FAIL (0x20044)The asyn parameter table is full. Increase MAX_PARAM_COUNT; see Asyn Parameter Count Exceeded. Sometimes referred to as ECMC_MAIN_ASYN_CREATE_PARAM_FAIL.
ERROR_AXIS_SLAVED_AXIS_INTERLOCKSlaved axis in error (synchronized axes).