Troubleshooting: Rail is getting hung, stuck, grinding, or moving in opposite direction

Rail is getting hung/stuck/grinding.

Special notes to read before following each step:

  • 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.
  • 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. See 3a and 3b for wire issues.

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 (BB Controller)


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?

3A) Checking the wire connections:


Are you using aftermarket cables (like route1 cables from etsy)? If so, the very first thing to do is remove them and replace them with the factory cables. Use of aftermarket cables will void your warranty. DO NOT CONTACT SUPPORT IF YOU ARE USING AFTER MARKET WIRING.

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
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:

Wire that comes out:

Elite with Masso controller with pushed in pin on back of screen for Y:

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.

3B) Please Follow this FAQ to determine if you have a bad motor or wire:

Replacement cables and motors can be purchased HERE:

4) Loose 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. There are two sides to the coupler! One holding it to the ball screw and one on the ball nut! Tighten both grub screws on BOTH sides by utilizing the access holes on front and back!

The red plastic spacer in the center of the couplers is NOT packaging and is required to operate the machine, do not throw these away
flexible coupler

This video will guide you through how to check this:

If the screws in the couplers are loose, it can cause an abrupt stop while jogging by sticking out too far and getting caught on the internal housing. See:

5) Ball Nut & Bearings

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!

How to clean the ball nuts: How to clean the ball nut on the Onefinity CNC // Support


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)


It’s also possible the bearings on the tubes have collected debris. It’s a good time to remove them and clean and flush them out as well.

Here’s a link showing how to remove the bearings: How To Adjust Bearing Stick Out On Rails

Example picture of dirty bearings

6) Maintenance:

Now is a good time to perform it via this video (let’s be honest, if you’re having to follow this guide, it’s already beyond time to do this :stuck_out_tongue: ): How to clean the ball nut on the Onefinity CNC // Support

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. Although this example is for a Y rail, the same principal applys to Y, B, and X axis. Usually, if a rail moves most of the way then ‘catches’ on the end, it can be a twisted rail.
Check out this video:

9) Final steps:

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