Skip to content

TROUBLESHOOTING.md

Latest commit

 

History

History
423 lines (312 loc) · 9.62 KB

TROUBLESHOOTING.md

File metadata and controls

423 lines (312 loc) · 9.62 KB
Raw

Troubleshooting Guide — Local Development

This guide documents the most common setup issues contributors encounter and how to fix them. If your problem is not listed here, please open a GitHub Issue.

Table of Contents

  1. Prerequisites Checklist
  2. Environment Variables
  3. Smart Contracts (Rust / Soroban)
  4. Listener Service (Node.js)
  5. Dashboard (React + Vite)
  6. General Issues

1. Prerequisites Checklist

Before starting, verify every tool is installed and working:

rustc --version          # Rust compiler
cargo --version          # Rust package manager
stellar --version        # Stellar CLI
node --version           # Node.js (v18+ recommended)
npm --version            # npm package manager

Install missing tools

Rust

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

WebAssembly target (required for Soroban contracts)

rustup target add wasm32-unknown-unknown

Stellar CLI

cargo install --locked stellar-cli --features opt

Node.js — download the LTS version from https://nodejs.org

2. Environment Variables

Listener Service (listener/.env)

Copy the example file and edit it:

cd listener
cp .env.example .env

Full reference with all available variables:

# ── Stellar Network ──────────────────────────────────────────────────────────
# RPC endpoint for the Stellar network to monitor
STELLAR_RPC_URL=https://soroban-testnet.stellar.org
# Network name (testnet, pubnet, or custom)
STELLAR_NETWORK=testnet
# JSON array of contract addresses to monitor
CONTRACT_ADDRESSES=[{"address":"CXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX","events":["*"]}]

# ── Listener API ─────────────────────────────────────────────────────────────
# Port the events HTTP API will listen on
EVENTS_API_PORT=8787
# How often (ms) the service polls for new on-chain events
POLL_INTERVAL_MS=30000

# ── Discord Notifications (optional) ─────────────────────────────────────────
DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/YOUR_WEBHOOK_ID/YOUR_TOKEN
DISCORD_WEBHOOK_ID=YOUR_WEBHOOK_ID

# ── Scheduler (optional) ─────────────────────────────────────────────────────
SCHEDULER_ENABLED=true
DATABASE_PATH=./data/notifications.db
SCHEDULER_POLL_INTERVAL_MS=10000
SCHEDULER_LOCK_TIMEOUT_MS=60000
SCHEDULER_BATCH_SIZE=10
SCHEDULER_TIMING_BUFFER_MS=60000
# Auto-generated if left empty
SCHEDULER_PROCESSOR_ID=

Tip for first-time contributors: You only need STELLAR_RPC_URL, CONTRACT_ADDRESSES, and EVENTS_API_PORT to run the listener locally. Everything else is optional.

Dashboard (dashboard/.env)

cd dashboard

Create a .env file:

# URL where your local listener is running
VITE_EVENTS_API_URL=http://localhost:8787/api/events

3. Smart Contracts (Rust / Soroban)

❌ error: toolchain 'stable' does not support target 'wasm32-unknown-unknown'

Cause: The WebAssembly target is not installed.

Fix:

rustup target add wasm32-unknown-unknown

❌ error[E0463]: can't find crate for 'std'

Cause: This happens when building without the correct target flag.

Fix: Always build with the wasm target:

cargo build --target wasm32-unknown-unknown --release
# or using Stellar CLI (handles the target automatically):
stellar contract build

❌ stellar: command not found

Cause: Stellar CLI is not installed or not in your PATH.

Fix:

cargo install --locked stellar-cli --features opt
# Then reload your shell:
source $HOME/.cargo/env

❌ Error: Contract not found when deploying

Cause: The .wasm file does not exist — the contract was not built first.

Fix:

# AutoShare contract
cd contract
stellar contract build

# TaskBounty contract
cd Documents/Task\ Bounty
stellar contract build

❌ Tests fail with error: no such file or directory

Cause: Running cargo test from the wrong directory.

Fix:

# AutoShare tests
cd contract/contracts/hello-world
cargo test

# TaskBounty tests
cd Documents/Task\ Bounty
cargo test

❌ Error: account not found when funding testnet identity

Cause: Friendbot rate limit or network issue.

Fix: Try again after a few seconds, or fund manually:

stellar keys generate my-identity --network testnet
stellar keys fund my-identity --network testnet

4. Listener Service (Node.js)

❌ Cannot find module / modules not found after cloning

Fix: Install dependencies first:

cd listener
npm install

❌ Error: Database not initialized or SQLITE_ERROR: no such table

Cause: The database migration has not been run.

Fix:

cd listener
npm run migrate

If the error persists:

# Make sure the data directory exists
mkdir -p data
NODE_ENV=development npm run migrate

❌ Error: Cannot find module 'sqlite3' (native module error)

Cause: Native bindings need to be rebuilt for your Node.js version.

Fix:

npm rebuild sqlite3

If that fails:

npm uninstall sqlite3
npm install sqlite3

❌ Listener starts but no events appear

Checklist:

  1. Is CONTRACT_ADDRESSES set correctly in your .env? 
    grep CONTRACT_ADDRESSES listener/.env
  2. Is the contract deployed on the same network as STELLAR_RPC_URL?
  3. Check live logs: 
    cd listener
npm run dev
# Look for lines like: "Received events" or "Processing event"
  4. Verify the API is responding: 
    curl http://localhost:8787/health
curl http://localhost:8787/api/events

❌ EADDRINUSE: address already in use :::8787

Cause: Port 8787 is already occupied by another process.

Fix (Linux/macOS):

lsof -i :8787
kill -9 <PID>

Fix (Windows):

netstat -ano | findstr :8787
taskkill /PID <PID> /F

Or change the port in your .env:

EVENTS_API_PORT=8788

❌ Discord notifications not being sent

Checklist:

  1. Is DISCORD_WEBHOOK_URL set in .env?
  2. Test the webhook manually: 
    curl -H "Content-Type: application/json" \
  -d '{"content": "test"}' \
  YOUR_DISCORD_WEBHOOK_URL
  3. Check logs for errors mentioning DiscordNotificationService.

5. Dashboard (React + Vite)

❌ Blank page or Failed to fetch error in the browser

Cause: The dashboard cannot reach the listener API.

Checklist:

  1. Is the listener running? (npm run dev inside listener/)
  2. Is VITE_EVENTS_API_URL set correctly in dashboard/.env? 
    # Should match the listener's API events endpoint
VITE_EVENTS_API_URL=http://localhost:8787/api/events
  3. Restart the Vite dev server after editing .env: 
    cd dashboard
npm run dev
  4. Check the browser console (F12 → Console) for CORS errors: 
    # If you see CORS errors, update listener/.env:
EVENTS_API_CORS_ORIGIN=http://localhost:5173

❌ Cannot find module after cloning

Fix:

cd dashboard
npm install

❌ TypeScript errors when running npm run build

Fix: Run the linter first to catch issues:

cd dashboard
npm run lint

Address any reported errors, then build again:

npm run build

❌ Dashboard shows stale data / events not updating

Cause: The listener is not polling or the event store is empty.

Fix:

  1. Confirm the listener is running and healthy: 
    curl http://localhost:8787/health
  2. Hard-refresh the browser (Ctrl + Shift + R / Cmd + Shift + R).
  3. Check the browser console for network errors (F12 → Console).

❌ Frontend (Next.js) page loads with data errors

Cause: The frontend cannot reach the listener API or the API URL is not configured.

Checklist:

  1. Is the listener running? (npm run dev inside listener/)
  2. If using a custom API URL, create frontend/.env.local: 
    NEXT_PUBLIC_API_URL=http://localhost:8787
  3. Restart the Next.js dev server after creating .env.local: 
    cd frontend
npm run dev

6. General Issues

❌ git clone fails (SSL / certificate error)

# Temporary workaround — reset after cloning
git config --global http.sslVerify false
git clone https://github.com/Core-Foundry/Notify-Chain.git
git config --global http.sslVerify true

❌ Everything worked before, now nothing works after a git pull

Run the full refresh sequence:

# Contracts
cd contract && stellar contract build

# Listener
cd ../listener && npm install && npm run migrate

# Dashboard
cd ../dashboard && npm install

Still stuck?

  1. Search open issues — your problem may already be reported.
  2. Open a new issue with:
    • Your OS and version
    • Output of rustc --version, node --version, stellar --version
    • The full error message
    • Steps you already tried