Troubleshooting: Rail is getting hung, stuck, or out of alignment

Rail is getting hung/stuck/grinding.

A rail getting stuck/hung is typically one of two things, either a wire/connection issue or the grub screw on the ball screw isn’t tight on the side that isn’t moving.
One thing to remember, stall homing adjustments do NOT affect rail movement during cutting or jogging. If the rail isn’t moving correctly during cutting or jogging, incorrect stall homing is an affect of this greater issue.
Note: Any time the axis moves in the opposite direction than what you direct it to, it’s 100% of the time a bad wire/connection. Sometimes, something as simple as disconnecting and reconnecting the wires connection solves it. Follow below for more help and examples.

1) Ensure you are on the latest firmware:

After updating, you must reset configuration, selecting your correct model: How To Reset The Configuration To Defaults

2) Diagnosing which rail is getting stuck:

First, it may sound silly, but ensure your wires are connected to the right rails. The easiest is to get the x and z crossed.

Next, we need to narrow down which rail isn’t moving correctly. For X and Z, this will be obvious, but for Y, since there are two rails moving simultaneously, we need to remove the x axis and place it between the two y rails. Then, jog the axis as fast as you can all the way to one end of the rail and then back 20 or so times. Does it make it without getting stuck? In the case of the Y axis, do both gantry blocks move in sync?

If you having an issue with the Z axis and have removed the curly cable (for aftermarket cable in a drag chain), the curly cable is required and has a wire cross. Without this, the Z axis will not work correctly. See Here: Onefinity Wiring Diagram

3) Checking the wire connections:

Disconnect all wires on the rail that isn’t moving, from controller to motor, triple check all 4 pins inside each connector are present, straight, and leveled with each other. Then reconnect all connections, ensuring they fit very snuggly and 'snap ’ together. Here’s some pictures of a bad wire and a pin pushed in.

Push in pin: bad wire on back side of connector.

Bad wire on backside of connector:

If a pin is pushed in, you can try grabbing it and pulling it forward with a pair of tweezers. If you cannot reach it this way, you can remove the tube following this video and push it back into place from the back of the connector. If it’s an inner tube wire, follow this video to gain access to the inside wire: Support : How to Access the inner tube motor wire

There is also a ‘hidden’ connection inside the tube (these inner tubes have a wire cross required for correct operation just like the z curly cable), where the motor and inner tube wire connect. You will need to watch the inner tube motor wire video (above) to check that connection as well. If you cannot remove the end cap to access the inner tube wire, you may need to use a dowl rod or the like to push it out from the backside in the tube.

Replacement cables and motors can be purchased HERE:

4) Loosen coupler on the ball screw and axis motor:

If there is not change after careful examination of each wire and connector on the bad rail, then check for a loose grub screw on the motor coupler. This video will guide you through how to check this:

5) Ball Nut

The below picture is a ‘defective’ rail that was returned to us. The culprit is very clearly debris in the rails. When pulling out the ball nut from the gantry, this is the amount of dust that just fell right out. This is one of the worst cases we’ve come across.

The gantry was getting ‘stuck/hung’ during movement, and after replacing wires and tightening grub screws, it persisted. Only when we took it apart at the factory did we discover the true issue.

It is extremely important to follow the Maintenance video. Proper dust extraction is also extremely important as well as removing the dust between carves.

Always make sure to keep your machine clean!

If your rail is getting hung, it could be dirt in the ball nut!

Here’s a video showing how to clean your ball nut: How to clean the ball nut on the Onefinity CNC // Support - YouTube


While working on the ball nut, there is a grub screw that holds the wiper (white ring) in place. If this grub screw is too tight, it will prevent the ball screw from spinning in the ball nut. You want this grub screw to be just barely into the white wiper to hold the wiper in place, but not so tight it squeezes the wiper against the screw.(see picture below, the green arrow is pointing to the grub screw)

6) Maintenance:

Now is a good time to perform it via this video: Onefinity CNC Maintenance

7) End Nut Adjustment

Ensure the nut on the rail end is properly tight. Too tight and the ball screw will not move, too loose, and the ball screw will not spin when the motor spins. There is a washer behind the nut. Proper tightness is when the washer behind the nut can just barely spin freely. Adjustments should be made in ¼ turns.

Foot Pound Torque Setting is around 4 lbf⋅ft ≈ 5.4 Nm

8) Ensure your rail sit’s flat.

Sometimes, twist can happen during shipping (we assemble rails on a flat granite table). Twist can cause binding of the rail. Check out this video:

9) Final steps:

Once you’ve gone through these steps, respond back to with your findings.