Troubleshooting

Common issues and their solutions when using React Native Reanimated DnD.

Setup Issues

"Component must be used within a DropProvider"

All Draggable, Droppable, Sortable, and SortableGrid components must be children of a DropProvider:

// Missing DropProvider
<View>
  <Draggable data={data}>...</Draggable>
</View>

// Wrapped in DropProvider
<DropProvider>
  <View>
    <Draggable data={data}>...</Draggable>
  </View>
</DropProvider>

Gestures Not Working

Missing GestureHandlerRootView: The app must be wrapped in GestureHandlerRootView, typically at the root:

import { GestureHandlerRootView } from "react-native-gesture-handler";

export default function App() {
  return (
    <GestureHandlerRootView style={{ flex: 1 }}>
      <DropProvider>
        {/* Your app content */}
      </DropProvider>
    </GestureHandlerRootView>
  );
}

Gesture conflict with ScrollView: If a draggable is inside a ScrollView, the scroll gesture may intercept the drag. Solutions:

Use a drag handle so only the handle triggers dragging
Use activationDelay to require a long press before dragging
Set simultaneousHandlers on the scroll view if using hooks directly

"Reanimated 4 is required"

This library requires React Native Reanimated 4.x. Check your installed version:

npm ls react-native-reanimated

If you're on Reanimated 3.x, upgrade:

npm install react-native-reanimated@latest

After upgrading, rebuild your native project:

# Expo
npx expo prebuild --clean
npx expo run:ios

# React Native CLI
cd ios && pod install && cd ..
npx react-native run-ios

Drag-and-Drop Issues

Draggable Item Not Moving

Check dragDisabled — Ensure it's not set to true:
```
<Draggable data={data} dragDisabled={false}>
```
Check for competing gesture handlers — If the draggable is inside a component that handles gestures (ScrollView, PanResponder, etc.), gestures may be intercepted.

Check layout — The draggable needs to have non-zero dimensions. Verify with a background color:

<Draggable data={data}>
  <View style={{ width: 100, height: 100, backgroundColor: "red" }}>
    <Text>Test</Text>
  </View>
</Draggable>

Drop Not Registering

Verify collision algorithm — With contain, the draggable must be fully inside the droppable. Try intersect for easier testing:
```
<Draggable data={data} collisionAlgorithm="intersect">
```
Check droppable capacity — If the droppable has a capacity limit that's been reached, drops will be rejected:
```
<Droppable
  onDrop={handleDrop}
  capacity={5} // Max 5 items
>
```

Verify DropProvider scope — The Draggable and Droppable must share the same DropProvider:

// Different providers — drops won't connect
<DropProvider>
  <Draggable data={data}>...</Draggable>
</DropProvider>
<DropProvider>
  <Droppable onDrop={handleDrop}>...</Droppable>
</DropProvider>

// Same provider
<DropProvider>
  <Draggable data={data}>...</Draggable>
  <Droppable onDrop={handleDrop}>...</Droppable>
</DropProvider>

Item Snaps Back Instead of Dropping

When a draggable doesn't collide with any droppable zone, it animates back to its original position. This is expected behavior. To debug:

Add activeStyle to your Droppable to see when collision is detected:

<Droppable
  activeStyle={{ borderColor: "green", borderWidth: 3 }}
  onDrop={handleDrop}
>

Check that the droppable has non-zero dimensions

Sortable List Issues

Items Not Reordering

Ensure onMove is implemented correctly — You must update your data array in response to the move callback:

<SortableItem
  onMove={(id, from, to) => {
    const newItems = [...items];
    const [moved] = newItems.splice(from, 1);
    newItems.splice(to, 0, moved);
    setItems(newItems);
  }}
>

Each item needs a unique id — Duplicate IDs cause position tracking to break:

// Duplicate IDs
const items = [{ id: "1" }, { id: "1" }];

// Unique IDs
const items = [{ id: "1" }, { id: "2" }];

itemHeight must be accurate — If itemHeight doesn't match the actual rendered height, position calculations will be wrong.

Auto-scroll Not Working

Auto-scroll triggers when a dragged item approaches the edges of the ScrollView. Ensure:

The list is actually scrollable (content taller than container)
You're using the Sortable component (it handles auto-scroll internally)
The scroll container has proper dimensions

Grid Issues

Grid Items Not Visible

This is usually caused by incorrect dimensions or the GestureDetector wrapper collapsing. Ensure:

Dimensions are provided correctly:

<SortableGrid
  dimensions={{
    columns: 4,
    itemWidth: 80,
    itemHeight: 80,
    rowGap: 12,
    columnGap: 12,
  }}
>

Items have explicit sizes — Grid items are absolutely positioned, so they need explicit width/height from the dimensions config.

// Triggers warning
const Component = () => {
  const offset = useSharedValue(0);
  const value = offset.value; // Reading during render
  return <Text>{value}</Text>;
};

// Use useAnimatedStyle or useDerivedValue instead
const Component = () => {
  const offset = useSharedValue(0);
  const animatedStyle = useAnimatedStyle(() => ({
    transform: [{ translateY: offset.value }],
  }));
  return <Animated.View style={animatedStyle} />;
};

Custom Animation Not Working

Ensure your animation function includes the "worklet" directive:

// Missing worklet directive
const animation = (toValue: number) => {
  return withSpring(toValue);
};

// Correct
const animation = (toValue: number) => {
  "worklet";
  return withSpring(toValue);
};

Build Issues

iOS Pod Install Failures

After installing or upgrading the library:

cd ios
pod deintegrate
pod install
cd ..

If using Expo:

npx expo prebuild --clean

Metro Bundler Cache

Stale Metro cache can cause mysterious errors. Clear it:

# Expo
npx expo start --clear

# React Native CLI
npx react-native start --reset-cache

Duplicate Module Errors

If you see errors about duplicate Reanimated or Worklets modules, clean your node_modules:

rm -rf node_modules
npm install  # or bun install / yarn install

# Then rebuild native:
cd ios && pod install && cd ..

Still Stuck?

Check the GitHub Issues — Your issue may already be reported
Create a minimal reproduction — Isolate the problem in a fresh project
File a new issue with:
- Library version
- React Native version
- Reanimated version
- Platform (iOS/Android)
- Minimal code to reproduce