Skip to content

TROUBLESHOOTING.md

Latest commit

 

History

History
312 lines (223 loc) · 7.47 KB

TROUBLESHOOTING.md

File metadata and controls

312 lines (223 loc) · 7.47 KB
Raw

Troubleshooting Guide

Common issues and solutions for Mova Store development and production.

Table of Contents

Development Setup

npm install fails

Symptoms: Error during dependency installation

Solutions:

  1. Clear npm cache:

    npm cache clean --force
rm -rf node_modules package-lock.json
npm install

  2. Check Node.js version (requires 18+):

    node --version

  3. On Mac, install Xcode tools:

    xcode-select --install

Environment variables not loading

Symptoms: App shows "Missing configuration" errors

Solutions:

  1. Ensure .env.local exists (copy from .env.local.example)
  2. Restart the dev server after changing env vars
  3. Verify variable names start with NEXT_PUBLIC_ for client-side access
  4. Check for typos in variable names

Supabase connection errors

Symptoms: Auth failures, empty shop, or "Invalid API key" in console

Solutions:

  1. Verify NEXT_PUBLIC_SUPABASE_URL and NEXT_PUBLIC_SUPABASE_ANON_KEY in .env.local
  2. Confirm the Supabase project is active
  3. Run supabase/schema.sql in the SQL editor
  4. Enable Email and/or Google providers under Authentication → Providers
  5. Add http://localhost:3000/** to Auth → URL Configuration → Redirect URLs

Wallet Connection

Freighter not detected

Symptoms: "Please install Freighter" message

Solutions:

  1. Install Freighter from freighter.app
  2. Enable the extension in browser settings
  3. Refresh the page
  4. Try a different browser (Chrome/Firefox)

Wrong network error

Symptoms: "Please switch to testnet/mainnet"

Solutions:

  1. Open Freighter → Settings → Network
  2. Select the correct network (Testnet or Mainnet)
  3. Refresh the page

Transaction signing fails

Symptoms: Freighter popup doesn't appear or closes immediately

Solutions:

  1. Ensure popup blockers are disabled
  2. Check Freighter is unlocked
  3. Verify the account has XLM for fees
  4. Check the transaction isn't malformed (look at console)

"Account not funded" error

Symptoms: Error when trying to pay on testnet

Solutions:

  1. Testnet: The app auto-funds via Friendbot, wait a moment
  2. If Friendbot fails, manually fund at https://friendbot.stellar.org
  3. Check account status: 
    stellar account info --network testnet <YOUR_PUBLIC_KEY>

Payment Issues

"Token not allowed" error

Symptoms: Payment fails with TokenNotAllowed

Solutions:

  1. Verify the token is whitelisted in the contract: 
    stellar contract invoke --id <CONTRACT_ID> --network testnet -- \
  is_token_allowed --token <TOKEN_CONTRACT_ID>
  2. Add the token if missing: 
    stellar contract invoke --id <CONTRACT_ID> --source-account <MERCHANT> --network testnet -- \
  add_token --token <TOKEN_CONTRACT_ID>

"Insufficient balance" error

Symptoms: Payment simulation fails with balance error

Solutions:

  1. Ensure user has enough tokens for the payment
  2. User needs XLM for transaction fees (~1 XLM recommended)
  3. For USDC, user needs a trustline (app creates automatically)

Transaction times out

Symptoms: "Transaction timed out" after 60 seconds

Solutions:

  1. Check Stellar network status: https://status.stellar.org
  2. Try a different RPC endpoint
  3. Increase timeout in lib/stellar/config.ts
  4. Check if transaction is actually pending on explorer

Payment succeeded but UI doesn't update

Symptoms: Funds moved but checkout stuck

Solutions:

  1. Check transaction on Stellar Expert
  2. Refresh the page
  3. Event indexer may be behind - wait a few seconds
  4. Check browser console for event polling errors

Admin Panel

"Access Denied" when accessing /admin

Symptoms: Logged in but can't access admin

Solutions:

  1. Verify your email is in NEXT_PUBLIC_ADMIN_EMAILS: 
    NEXT_PUBLIC_ADMIN_EMAILS=your@email.com,other@admin.com
  2. Emails are case-insensitive but check for typos
  3. Restart the app after changing admin emails

Products not loading

Symptoms: Admin panel shows loading or empty

Solutions:

  1. Check RLS policies allow read access on products
  2. Verify the products table exists (run supabase/schema.sql)
  3. Check browser console for Supabase errors
  4. Ensure the products storage bucket is public

Can't dispatch/refund orders

Symptoms: Action buttons fail with error

Solutions:

  1. Connect Freighter with the merchant wallet (the one used to initialize contract)
  2. Check order status is "Paid" (can only dispatch/refund paid orders)
  3. Verify you're on the correct network (testnet/mainnet)

Contract Deployment

Build fails

Symptoms: stellar contract build or cargo build errors

Solutions:

  1. Install wasm target: 
    rustup target add wasm32-unknown-unknown
  2. Update Rust: 
    rustup update
  3. Clean and rebuild: 
    cd contracts/checkout
cargo clean
cargo build --target wasm32-unknown-unknown --release

Deploy fails with "account not found"

Symptoms: Deployment fails with account error

Solutions:

  1. Ensure deployer account is funded: 
    stellar keys generate alice --network testnet --fund
  2. Check account exists: 
    stellar account info --network testnet --source-account alice

Initialize fails

Symptoms: "AlreadyInitialized" or authorization error

Solutions:

  1. Contract can only be initialized once
  2. The merchant address must sign the initialization
  3. For a fresh start, deploy a new contract instance

Build & Deploy

Next.js build fails

Symptoms: npm run build errors

Solutions:

  1. Check TypeScript errors: 
    npm run type-check
  2. Fix ESLint issues: 
    npm run lint:fix
  3. Ensure all env vars are set (even placeholder values)

Vercel deployment fails

Symptoms: Build or deploy errors on Vercel

Solutions:

  1. Check all environment variables are set in Vercel dashboard
  2. Verify Node.js version in package.json engines
  3. Check build logs for specific errors
  4. Try local build first: npm run build

Images not loading in production

Symptoms: Product images 404 or broken

Solutions:

  1. Check Supabase Storage public bucket settings for products
  2. Verify NEXT_PUBLIC_SUPABASE_URL matches your project
  3. Confirm image URLs use /storage/v1/object/public/products/...
  4. Check storage RLS policies for the products bucket

Getting Help

If you can't resolve an issue:

  1. Search existing issues: GitHub Issues
  2. Check Stellar docs: developers.stellar.org
  3. Ask in Discord: Stellar Discord
  4. Open a new issue with:
    • Error message
    • Steps to reproduce
    • Environment (OS, Node version, browser)
    • Relevant logs

Debug Mode

Enable verbose logging:

// In browser console
localStorage.setItem('debug', 'mova-store:*');

Check Stellar transaction details:

stellar tx details <TX_HASH> --network testnet

Monitor contract events:

stellar events --id <CONTRACT_ID> --network testnet --start-ledger <LEDGER>