Troubleshooting

Varity Team Core Contributors Updated March 2026

Solutions to common issues when building with Varity.

Installation Issues

”command not found: varitykit”

The CLI is not installed or is not in your PATH.

1. Install the CLI:

   pip install varitykit

2. Verify installation:

   varitykit --version

3. If still not found, check your Python path:

   python -m varitykit --version

“ModuleNotFoundError: No module named ‘varitykit’”

Python dependencies are missing.

pip install --upgrade varitykit

Package installation fails

If npm package installation fails:

# Clear npm cache
npm cache clean --force

# Delete node_modules and reinstall
rm -rf node_modules package-lock.json
npm install

Deployment Issues

”Credentials not found”

Credentials are managed automatically by Varity. Run varitykit doctor to verify your setup. See Managed Credentials.

”Build failed”

1. Verify your build works locally:

   npm run build

2. Check for TypeScript errors:

   npx tsc --noEmit

3. Ensure all dependencies are installed:

   npm install

“Upload failed”

Possible causes and solutions:

Cause	Solution
Network timeout	Try again - temporary network issue
Large files	Split into smaller chunks
Rate limiting	Wait a few minutes and retry
Credentials issue	Run varitykit doctor to verify

Authentication Issues

”PrivyStack: appId is required”

Set your Auth App ID in environment variables:

.env.local

NEXT_PUBLIC_PRIVY_APP_ID=your_app_id

Or use Varity development credentials (the SDK will use defaults if none provided).

Login button not appearing

1. Verify PrivyStack wraps your application:

   <PrivyStack appId={process.env.NEXT_PUBLIC_PRIVY_APP_ID}>
     <App />
   </PrivyStack>

2. Check browser console for errors

3. Ensure environment variables are loaded (restart dev server)

“Domain not allowed” error

Your domain needs to be allowed for authentication. Contact support@varity.so to allow your domain, or include localhost for local development.

Session not persisting

Tip

Sessions are stored in localStorage. Private browsing or clearing storage will log users out.

Check that:

• PrivyStack is at the root of your app
• You’re not accidentally clearing localStorage
• Cookies are enabled in the browser

Build Issues

TypeScript errors in Varity packages

Ensure you’re using compatible TypeScript version:

package.json

{
  "devDependencies": {
    "typescript": "^5.0.0"
  }
}

“Cannot find module ‘@varity-labs/sdk’”

1. Install packages:

   npm install @varity-labs/sdk @varity-labs/ui-kit @varity-labs/types

2. Check package.json includes the dependencies

3. Clear and reinstall:

   rm -rf node_modules
   npm install

“React version mismatch”

Varity UI Kit requires React 18+:

package.json

{
  "dependencies": {
    "react": "^18.0.0",
    "react-dom": "^18.0.0"
  }
}

Runtime Issues

”Network request failed”

Check network connectivity:

varitykit doctor

This will verify your connection to Varity’s infrastructure.

”Operation failed”

Common causes:

Error	Solution
Insufficient funds	Operations are free — contact support
Service not found	Verify configuration is correct
Invalid parameters	Check function arguments

Slow performance

1. Enable production mode:

   npm run build && npm start

2. Check bundle size:

   npm run analyze

3. Verify you’re using tree-shaking:

   // Good - tree-shakeable
   import { PrivyStack } from '@varity-labs/ui-kit';
   
   // Avoid - imports entire package
   import * as VarityUI from '@varity-labs/ui-kit';

CLI Issues

”varitykit doctor” shows failures

Run the doctor command to diagnose:

varitykit doctor

Common failures and fixes:

Check	Fix
Environment variables	Create .env file with required vars
Network connectivity	Check internet connection
Project structure	Ensure package.json exists
Dependencies	Run npm install

Deployment history not showing

Deployments are stored locally. Check:

ls ~/.varitykit/deployments/

If empty, no deployments have been made from this machine.

Getting More Help

If you’re still stuck:

1. Search existing issues: GitHub Issues

2. Ask the community: Discord

3. Open a new issue with:

   • Error message (full stack trace)
   • Steps to reproduce
   • varitykit doctor output
   • OS and Node.js version

4. Email support: support@varity.so