Jumpbox Logo
DocumentationTroubleshooting

Troubleshooting Guide

Common issues and solutions for $JUMPBOX.ETH ecosystem components. Find quick fixes for wallet connections, API problems, authentication errors, and deployment issues.

Table of Contents

Quick Fixes

Try these common solutions first before diving into specific issues:

Clear Browser Cache

Force refresh with Ctrl+F5 or Cmd+Shift+R

Check Console Errors

Open browser DevTools and check Console tab

Verify Environment Variables

Ensure all required API keys are set correctly

Test Network Connection

Try accessing APIs directly with curl or browser

Review Recent Changes

Check git history for breaking changes

Update Dependencies

Run npm update to get latest package versions

Wallet Connection Issues

Problem:

Infinite loading screen in Farcaster Mini App

Solution:

Make sure you call sdk.actions.ready() after your app loads

import { sdk } from '@farcaster/miniapp-sdk';

useEffect(() => {
  const initializeApp = async () => {
    await sdk.actions.ready(); // This hides splash screen
  };
  initializeApp();
}, []);

Problem:

Wallet connection fails with Wagmi

Solution:

Verify you are using the official Farcaster connector

import { farcasterMiniApp as miniAppConnector } from '@farcaster/miniapp-wagmi-connector';

export const config = createConfig({
  chains: [base],
  connectors: [
    miniAppConnector() // Use official connector
  ]
});

Problem:

Transaction fails with "user rejected" error

Solution:

Check transaction parameters and ensure valid addresses/amounts

// Validate inputs before sending
if (!isAddress(toAddress)) {
  throw new Error('Invalid address');
}
if (amount <= 0) {
  throw new Error('Amount must be positive');
}

Balance Check Problems

Problem:

useReadContract returns undefined for token balance

Solution:

Check contract address and ensure network is correct

const { data: balance } = useReadContract({
  address: '0x5B9957A7459347163881d19a87f6DC13291C2B07', // Verify address
  abi: ERC20_ABI,
  functionName: 'balanceOf',
  args: [userAddress],
  enabled: !!userAddress, // Only run when address exists
});

Problem:

Balance shows as 0 but user has tokens

Solution:

Verify you are on the correct network and using right decimals

// Check network and format properly
const formattedBalance = balance ? 
  formatUnits(balance, 18) : // Use correct decimals
  '0';

Problem:

RPC connection errors during balance checks

Solution:

Add error handling and retry logic

const { data: balance, error, isLoading } = useReadContract({
  // ... contract config
  query: {
    retry: 3,
    retryDelay: 1000,
  }
});

if (error) {
  console.error('Balance check failed:', error);
}

Social Resource Access

Problem:

Cannot access Farcaster user data

Solution:

Ensure Mini App context is properly initialized

import { sdk } from '@farcaster/miniapp-sdk';

const [context, setContext] = useState(null);

useEffect(() => {
  const getContext = async () => {
    try {
      const ctx = await sdk.context();
      setContext(ctx);
    } catch (error) {
      console.error('Failed to get context:', error);
    }
  };
  getContext();
}, []);

Problem:

Top Holders Chat access denied

Solution:

Verify token balance meets minimum requirements

// Check if user meets requirements
const MIN_TOKENS_FOR_ACCESS = 1000000000; // 1B tokens

if (tokenBalance >= MIN_TOKENS_FOR_ACCESS) {
  // User has access
} else {
  // Show requirement message
}

Problem:

Profile picture or user data not loading

Solution:

Handle undefined data and add fallbacks

const userData = context?.user;
const profileImage = userData?.pfpUrl || '/default-avatar.png';
const displayName = userData?.displayName || userData?.username || 'User';

Common Issues by Category

Authentication

API keys not working

Use environment variables, never hardcode credentials

$env:API_TOKEN = "your_token" # PowerShell

401 Unauthorized errors

Check token format and expiration

"Authorization" = "Bearer $env:API_TOKEN"

CORS errors in browser

API calls should be made server-side when possible

Use Next.js API routes for sensitive operations

Network Issues

Timeout errors with PowerShell scripts

Increase timeout values for slower APIs

Invoke-RestMethod -Uri $uri -TimeoutSec 60

SSL certificate errors

For testing only: bypass SSL validation

[System.Net.ServicePointManager]::ServerCertificateValidationCallback = {$true}

Rate limiting from APIs

Add delays between requests

Start-Sleep -Milliseconds 1000 # 1 second delay

Build & Deployment

localStorage undefined during build

Add client-side checks for browser APIs

if (typeof window !== "undefined") { localStorage.getItem(...) }

Dynamic server usage errors

Avoid request.url in API routes during static generation

Use static configuration instead of dynamic URLs

Import errors with dependencies

Check exact package versions and imports

import { GraduationCap } from "lucide-react" // Not GraduationCat

Farcaster Mini App Issues

Loading Screen Problems

Issue: App stuck on loading

Missing sdk.actions.ready() call

await sdk.actions.ready();

Context Access Issues

Issue: User data undefined

Context not properly awaited

const context = await sdk.context();

Performance Problems

Common Performance Issues

Slow API Calls
  • • Implement proper loading states
  • • Add request caching with React Query
  • • Use pagination for large datasets
  • • Set appropriate timeout values
Memory Issues
  • • Use useMemo for expensive calculations
  • • Implement proper cleanup in useEffect
  • • Avoid memory leaks with event listeners
  • • Optimize image loading and sizing
Example: Optimized API Call
const { data, isLoading, error } = useQuery({
  queryKey: ['balance', address],
  queryFn: () => getTokenBalance(address),
  staleTime: 30000, // Cache for 30 seconds
  enabled: !!address // Only run when address exists
});

Getting Help

Before Asking for Help

  • Search this documentation first
  • Check browser console for error messages
  • Look through GitHub issues in relevant repos
  • Try to reproduce the issue with minimal code

Reporting Issues

When reporting bugs, include:

  • • Exact error messages
  • • Steps to reproduce
  • • Browser and version
  • • Code snippets (minimal example)
  • • Expected vs actual behavior
  • • Screenshots if relevant
GitHub Issues
Report bugs and request features
FAQ
Frequently asked questions
Official Docs
Farcaster Mini Apps documentation

Emergency Fixes

If you're experiencing critical issues in production:

Immediate Actions

  • 1. Check if the issue affects all users
  • 2. Look for recent deployments or changes
  • 3. Monitor error rates and user reports
  • 4. Consider rolling back recent changes

Quick Diagnostics

  • • Check application logs and metrics
  • • Verify API endpoints are responding
  • • Test wallet connections manually
  • • Confirm environment variables are set