Troubleshooting

Common Issues

1. Wallet Connection Issues

   • Ensure you have the wallet extension installed and configured properly

   • Check if the wallet is connected to the correct Cardano network

   • Try refreshing the page or reconnecting the wallet

2. Transaction Errors

   • Verify you have sufficient ADA for transaction fees

   • Check wallet UTXOs for conflicts

   • Ensure correct token amounts are specified

3. CORS Errors

   • Configure and use local-cors-proxy for API requests

   • Ensure your config points to the correct proxy URL

4. Node Version Incompatibility

   • Error: "Cannot find module 'node:fs'"

   • Solution: Ensure you're using Node.js v16 or higher

   • To check your Node version: node --version

   • To install/update Node.js:

     # Using nvm (Node Version Manager)
     nvm install 16
     nvm use 16
     
     # Or download directly from nodejs.org

5. Dependency Installation Failures

   • Error: "Failed to install dependencies"

   • Solution: Try clearing npm/yarn cache:

     npm cache clean --force
     # or
     yarn cache clean

   • If issues persist, try:

     rm -rf node_modules
     rm package-lock.json # or yarn.lock
     npm install # or yarn install

   • For network issues:

     # Configure npm to use a different registry
     npm config set registry https://registry.npmjs.org/
     
     # Or use a different DNS
     npm config set dns_server 8.8.8.8

6. Port Already in Use

   • Error: "Port 3000 is already in use"

   • Solution: Either kill the process using port 3000 or use a different port:

     PORT=3001 npm start

   • To find and kill the process:

     # On Unix-based systems
     lsof -i :3000
     kill -9 <PID>
     
     # On Windows
     netstat -ano | findstr :3000
     taskkill /PID <PID> /F

7. TypeScript Errors

   • Error: "Type 'X' is not assignable to type 'Y'"

   • Solution: Check type definitions in src/types directory

   • Run type checking: npm run type-check

   • Common fixes:

     // Add type assertion
     const value = someValue as ExpectedType;
     
     // Use type guard
     if (isExpectedType(someValue)) {
       // TypeScript knows the type here
     }
     
     // Update type definition
     interface MyType {
       property: string;
     }

8. Build Failures

   • Error: "Failed to compile"

   • Common causes and solutions:

     • Syntax errors: Check for missing semicolons, brackets

     • Missing dependencies: Run npm install or yarn install

     • Type errors: Run npm run type-check

     • Memory issues: Increase Node.js memory limit:

       export NODE_OPTIONS=--max-old-space-size=4096