Overview
This guide covers the most common issues you’ll encounter when building crypto applications with AI assistance, along with proven solutions and debugging strategies.Starter App Variations: Different CDP starter apps may use different commands, scripts, and patterns. Always check your specific starter app’s documentation and package.json for the correct commands.
Build and Deployment Issues
Linting errors
Linting and Code Style Errors
Linting and Code Style Errors
Problem: Build fails with linting or code style errors after AI generates codeGeneral debugging approach:Useful resources:
- Check your package.json - Look for linting scripts (could be
lint,eslint,prettier, etc.) - Run the linting command - Each starter app may have different commands
- Fix one error at a time - Start with the first error in the output
- Look for auto-fix options - Many linters have
--fixflags
- Check your starter app’s README for linting setup
- Look at your starter app’s existing code style patterns
- Different starter apps may use ESLint, Prettier, or other tools
TypeScript Type Errors
TypeScript Type Errors
Problem: AI-generated code has TypeScript errorsGeneral debugging approach:Useful resources:
- Read the error message carefully - TypeScript errors are usually specific
- Fix one error at a time - Start from the top of the error list
- Check imports - Make sure you’re importing types from the right packages
- Look at existing code - See how your starter app handles similar patterns
- Check your starter app’s TypeScript configuration
- Look at how existing components in your starter app handle types
- Different starter apps may have different type patterns for crypto functionality
- TypeScript documentation for general TypeScript issues
Package installation issues
Dependency Conflicts
Dependency Conflicts
Problem: npm install fails with peer dependency warningsGeneral debugging approach:Useful resources:
- Read the warning carefully - Peer dependency warnings often suggest solutions
- Check your starter app’s documentation - It may have specific setup instructions
- Try standard npm troubleshooting - Clear cache and reinstall dependencies
- Check your starter app’s installation instructions
- Different starter apps may have different dependency management approaches
OnchainKit Component Issues
OnchainKit Component Issues
Problem: OnchainKit components not working after AI generates codeDebugging steps:Useful resources:
- Check your package.json - See which OnchainKit version you’re using
- Look at existing components - See how OnchainKit is used in your starter app
- Verify imports - Make sure you’re importing from the correct OnchainKit modules
- Check component documentation - APIs may vary between versions
- OnchainKit Documentation
- OnchainKit Components
- Check your starter app’s existing OnchainKit usage patterns
Runtime errors
Wallet connection issues
Wallet Connection Fails
Wallet Connection Fails
Problem: Users can’t connect their walletGeneral debugging approach:Useful resources:
- Check browser console - Look for connection errors or warnings
- Test with Coinbase Wallet - Ensure Coinbase Wallet is installed and working
- Verify network settings - Make sure your app and wallet are on the same network
- Test on different browsers - Try Chrome, Safari, or Firefox
- HTTPS required - Wallet connections don’t work on HTTP in production
- Network mismatch - Ensure wallet is on the correct chain (Base, Ethereum, etc.)
- Browser compatibility - Make sure your browser supports wallet connections
- Clear cache - Try clearing browser cache and refreshing the page
- Check your starter app’s documentation for wallet connection patterns
- OnchainKit Wallet Documentation
Transaction Failures
Transaction Failures
Problem: Transactions fail or get stuckGeneral debugging approach:General debugging steps:
- Check transaction details - Look at the error message for specific reasons
- Verify gas settings - Make sure you have enough ETH for gas fees
- Check network status - Network congestion can cause delays
- Test with small amounts - Start with minimal values for testing
- User rejected - User cancelled the transaction in their wallet
- Insufficient funds - Not enough ETH for gas or tokens for transfer
- Network timeout - Transaction took too long (try increasing gas)
- Invalid parameters - Check recipient address and amounts
- Add console.log statements to track transaction progress
- Check wallet for pending transactions
- Verify contract addresses and function parameters
- Test on testnet first with fake tokens
- Check your starter app’s transaction patterns
- Use block explorers (Basescan, Etherscan) to inspect failed transactions
API integration issues
CDP API Authentication
CDP API Authentication
Problem: CDP API calls return 401 UnauthorizedCheck these items:Useful resources:
- API keys are correctly set in environment variables
- Environment variable names match exactly (case-sensitive)
- API keys are valid and not expired
- Project ID matches your CDP project
- Use the CDP SDK instead of raw API calls when possible
- Check environment variables - Print them (safely) to verify they’re loaded
- Test with a simple API call first
- Read the response - 401 errors often include helpful details
- CDP Authentication Guide
- CDP SDK Documentation
- Use the CDP SDK for automatic JWT generation
Rate Limiting Issues
Rate Limiting Issues
Problem: API calls fail with 429 Too Many RequestsGeneral debugging approach:Useful resources:
- Reduce API call frequency - Space out your requests
- Check rate limits - Review your API plan’s rate limits
- Implement retry logic - Wait before retrying failed requests
- Use caching - Avoid unnecessary duplicate API calls
- CDP API Documentation for rate limit details
- Check your starter app’s API usage patterns
AI-generated code issues
Code quality problems
AI Generated Insecure Code
AI Generated Insecure Code
Problem: AI generates code with security vulnerabilitiesSecurity review checklist:Useful resources:
- Input validation is present
- API keys are not hardcoded
- User inputs are sanitized
- Error messages don’t leak sensitive information
- Rate limiting is implemented for API calls
- CDP Security Documentation
- Check your starter app’s security patterns
- Consider security code reviews for production apps
Performance Issues
Performance Issues
Problem: AI-generated code is slow or inefficientGeneral debugging approach:Useful resources:
- Identify the bottleneck - Use browser dev tools to find slow operations
- Check network requests - Look for unnecessary API calls or large responses
- Review rendering - See if components are re-rendering too often
- Test on different devices - Performance varies across devices
- Check your starter app’s performance optimization patterns
- Use React DevTools or browser performance tools for analysis
Logic errors
Incorrect Blockchain Interactions
Incorrect Blockchain Interactions
Problem: AI generates incorrect smart contract interactionsGeneral debugging approach:Useful resources:
- Test on testnet first - Always verify logic with test tokens
- Check contract ABI - Ensure function signatures match
- Validate parameters - Verify data types and formats
- Use block explorer - Check actual transaction details on Basescan or Etherscan
- Check your starter app’s smart contract interaction patterns
- Use block explorers to verify contract addresses and ABIs
- Test all interactions on testnet before mainnet
Environment-specific issues
Local development
HTTPS Requirements
HTTPS Requirements
Problem: Wallet connections fail in local developmentGeneral debugging approach:Useful resources:
- Check if HTTPS is required - Most wallet connections need HTTPS
- Look for HTTPS solutions - Check your starter app’s development setup
- Test on different browsers - Some browsers have different requirements
- Check console errors - Look for specific security or connection errors
- Check your starter app’s local development documentation
- Different starter apps may have different HTTPS setup methods
Environment Variables Not Loading
Environment Variables Not Loading
Problem: Environment variables are undefined in developmentGeneral debugging approach:Useful resources:
- Check your starter app’s .env.example - This shows the correct variable names and format
- Verify file name - Most Next.js apps use
.env.localfor local development - Restart development server - Environment variables are loaded at startup
- Check for syntax errors - No spaces around
=signs, proper quotes
- Check your starter app’s .env.example file for the correct variable names and patterns
- Different starter apps may use different environment variable naming conventions
Production issues
Vercel Deployment Failures
Vercel Deployment Failures
Problem: App builds locally but fails on VercelGeneral debugging approach:Useful resources:
- Check build logs in Vercel dashboard for specific errors
- Verify environment variables are set correctly in Vercel settings
- Test production build locally - Check your package.json for build scripts
- Check for differences between local and production environments
- Vercel Documentation for deployment troubleshooting
- Check your starter app’s deployment documentation
Getting help
AI debugging prompts
When asking AI for help with errors, provide this context for better results:Community resources
- CDP Discord: Real-time community support
- GitHub Discussions: Technical Q&A
- OnchainKit Issues: Component-specific issues
What to read next
- AI Prompting Techniques: Effective AI interaction patterns
- Deployment Guide: Smooth deployment workflows
- Development Workflows: Advanced patterns