Troubleshooting

Verify your versions

Install native packages with npx expo install, never with npm install alone: it picks the versions your SDK supports. To check what you already have:

npx expo install --check

Your account does not include an animation

add stops with Your account does not include <id> when the account you signed in with has not bought that piece. Run npx nativeanimation list to see what your account includes, and check that the terminal is signed in with the account you bought with. All-access includes every animation.

Your session is invalid or has expired

Run npx nativeanimation login again. A token you revoked from your account page stops working on that machine. In CI, set NATIVEANIMATION_TOKEN instead of signing in.

The CLI will not overwrite my files

When a file already exists and differs, add stops instead of replacing your edits. Preview the change with --dry-run, then pass --overwrite if you want the new version. Identical files are left untouched.

The import path does not resolve

The examples import from @/components/<id>. If your project has no @/ alias, import with a relative path, or add the alias to tsconfig.json:

{
  "compilerOptions": {
    "paths": { "@/*": ["./src/*"] }
  }
}

Expo reads paths from tsconfig.json without extra configuration. If the files went to another folder, use --path or a nativeanimation.json file (see CLI).

Gestures do nothing

Animations with gestures need your app wrapped in GestureHandlerRootView once, at the root:

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

export default function RootLayout() {
  return <GestureHandlerRootView style={{ flex: 1 }}>{/* your app */}</GestureHandlerRootView>;
}

Errors about worklets after installing

babel-preset-expo adds the Worklets Babel plugin by itself when react-native-worklets is installed, so you do not need a babel.config.js for it. After adding new packages, restart Metro with a clean cache:

npx expo start --clear

A Skia animation is blank on the web

Pieces that draw with Skia need CanvasKit loaded before they mount on the web. See Skia pieces on the web. iOS and Android need nothing extra.

The animation stays still

When Reduce Motion is on in the device settings, animations switch to their still or cross-fade version. That is intended. Turn the setting off to see the full motion.

Does it run in Expo Go?

Each published piece is reviewed on physical iPhone and Android devices with Expo Go before release. Check the SDK-specific dependencies on its animation page. A custom native dependency outside Expo Go requires a development build.

My coding agent cannot add animations

Base setup and installation, search, and public documentation work without an account. Adding other catalog pieces needs a session: run npx nativeanimation login once in a terminal. If your MCP client starts servers outside your project folder, the agent has to pass the absolute project path in project_root. Setup for each client: MCP server.

Other issues

Write to support@nativeanimation.com with the animation id, your Expo SDK, the platform and the full error. Run the CLI with NATIVEANIMATION_DEBUG=1 to print the full error details.