From 638bedd03c74f9e8e41ae3662a3cbff596186f99 Mon Sep 17 00:00:00 2001 From: edochieblessing09-max Date: Thu, 30 Jul 2026 07:21:30 +0100 Subject: [PATCH] docs: add troubleshooting guide with 10 documented issues --- CONTRIBUTING.md | 3 ++ README.md | 4 ++ docs/TROUBLESHOOTING.md | 87 +++++++++++++++++++++++++++++++++++++++++ 3 files changed, 94 insertions(+) create mode 100644 docs/TROUBLESHOOTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 73f99484..0f3c1595 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -16,6 +16,7 @@ Thank you for your interest in contributing to **Stellar Goal Vault**! - Read the [README.md](./README.md) for project overview and architecture. - Check the [FAQ.md](./FAQ.md) for answers to common questions. +- See the [Troubleshooting Guide](./docs/TROUBLESHOOTING.md) for solutions to common development issues. - Browse `OPEN_SOURCE_ISSUES.md` for curated contribution ideas. ## Backend Development @@ -104,6 +105,8 @@ Thank you for your interest in contributing to **Stellar Goal Vault**! ### Troubleshooting +See the [Troubleshooting Guide](./docs/TROUBLESHOOTING.md) for a comprehensive list of common issues. + #### "SQLITE_CANTOPEN" or database file not found - Ensure the directory specified in `DB_PATH` exists - Check file permissions on the database directory diff --git a/README.md b/README.md index 538c1cfc..c269fc3f 100644 --- a/README.md +++ b/README.md @@ -542,6 +542,10 @@ That issue is already represented in: See the [FAQ.md](./FAQ.md) for answers to common questions about testnet funding, Freighter setup, contract deployment, database reset, pledge failures, and more. +## Troubleshooting + +See the [Troubleshooting Guide](./docs/TROUBLESHOOTING.md) for solutions to common issues like SQLite permissions, Soroban CLI mismatches, and CORS errors. + ## Security Please see [SECURITY.md](./SECURITY.md) for our responsible disclosure policy, supported versions, and reporting instructions. diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md new file mode 100644 index 00000000..f1600148 --- /dev/null +++ b/docs/TROUBLESHOOTING.md @@ -0,0 +1,87 @@ +# Troubleshooting Guide + +This guide covers common issues encountered while developing, building, or running the application. + +## 1. SQLite File Permission Errors +**Symptom**: `Error: SQLITE_CANTOPEN: unable to open database file` when starting the backend. +**Cause**: The process running the backend does not have write permissions to the directory where the SQLite database file is stored or to the file itself. +**Fix**: Grant appropriate read/write permissions to the database file and its parent directory. +```bash +chmod 755 backend/data +chmod 644 backend/data/campaigns.db +``` + +## 2. Soroban CLI Version Mismatch +**Symptom**: `error: Found argument '--network' which wasn't expected` or unexpected CLI behavior when deploying contracts. +**Cause**: You have an outdated or newer version of the Soroban CLI installed globally that is incompatible with the project's contract scripts. +**Fix**: Install the specific version of Soroban CLI required by the project using cargo. +```bash +cargo install --locked --version 20.0.0 soroban-cli +``` + +## 3. Freighter Connection Issues +**Symptom**: "Freighter is not installed" or "Connection rejected" in the web application. +**Cause**: The Freighter browser extension is not installed, the user denied the connection request, or the extension is locked. +**Fix**: Reset the local network configuration via CLI to ensure proper testnet connections if local accounts are used. +```bash +stellar network add --global testnet --rpc-url https://soroban-testnet.stellar.org:443 +``` + +## 4. CORS Errors +**Symptom**: `Access to fetch at 'http://localhost:8000/api/...' from origin 'http://localhost:3000' has been blocked by CORS policy.` +**Cause**: The backend server is not configured to allow cross-origin requests from the frontend development server. +**Fix**: Update your backend environment variables to allow the frontend origin, or restart the backend with CORS enabled. +```bash +export CORS_ALLOWED_ORIGINS="http://localhost:3000" +npm run dev --prefix backend +``` + +## 5. Contract ID Not Set +**Symptom**: `Error: Contract ID not configured` when attempting to invoke a contract function from the frontend. +**Cause**: The compiled contract ID is missing from the environment configuration files. +**Fix**: Rebuild the contracts and copy the generated contract ID into your backend `.env` file. +```bash +soroban contract deploy --wasm target/wasm32-unknown-unknown/release/contract.wasm --source account > backend/.env.contract +``` + +## 6. Node Version Mismatch +**Symptom**: `SyntaxError: Unexpected token '?'` or package installation failures during `npm install`. +**Cause**: You are using an unsupported version of Node.js. +**Fix**: Switch to the recommended Node.js version (e.g., v18 or v20) using nvm. +```bash +nvm install 18 +nvm use 18 +``` + +## 7. Docker Daemon Not Running +**Symptom**: `Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?` +**Cause**: The Docker background service is not running on your host machine. +**Fix**: Start the Docker service systemd. +```bash +sudo systemctl start docker +sudo systemctl enable docker +``` + +## 8. Environment Variables Not Loaded +**Symptom**: Application starts but immediately crashes with missing configuration errors. +**Cause**: The `.env` file is missing or not being properly sourced in the backend directory. +**Fix**: Copy the example environment file and populate it. +```bash +cp backend/.env.example backend/.env +``` + +## 9. Network Timeout on Testnet +**Symptom**: `Timeout waiting for transaction confirmation` when interacting with the Stellar Testnet. +**Cause**: Network congestion or the RPC node is temporarily unreachable. +**Fix**: Ping the RPC endpoint to check availability. +```bash +curl -X POST "https://soroban-testnet.stellar.org:443" -d '{"jsonrpc":"2.0","id":1,"method":"getNetwork"}' +``` + +## 10. Insufficient Funds in Testnet Account +**Symptom**: `op_underfunded` or `tx_insufficient_balance` when submitting a transaction. +**Cause**: The account signing the transaction does not have enough XLM to cover the network fees and minimum balance requirements. +**Fix**: Fund your account using the Stellar Friendbot. +```bash +curl "https://friendbot.stellar.org/?addr=YOUR_PUBLIC_KEY" +```