docs: add troubleshooting guide with 10 documented issues #757
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 | ||
| ``` | ||
|
Comment on lines
+14
to
+20
There was a problem hiding this comment. 🎯 Functional Correctness | 🟠 Major | ⚡ Quick win 🧩 Analysis chain🏁 Script executed: rg -n 'soroban-cli|stellar-cli|soroban |stellar ' --glob '!node_modules/**' .Repository: ritik4ever/stellar-goal-vault Length of output: 3576 🏁 Script executed: #!/bin/bash
set -euo pipefail
echo "== docs/TROUBLESHOOTING.md lines 1-60 =="
cat -n docs/TROUBLESHOOTING.md | sed -n '1,60p'
echo
echo "== scripts/deploy.sh CLI checks/invocations =="
cat -n scripts/deploy.sh | sed -n '30,90p'
echo
echo "== README stellar invocations =="
cat -n README.md | sed -n '60,170p'
echo
echo "== package/tooling references =="
for f in package.json Cargo.toml Cargo.lock justfile README.md; do
[ -f "$f" ] && { echo "--- $f"; sed -n '1,140p' "$f"; }
doneRepository: ritik4ever/stellar-goal-vault Length of output: 17565 🌐 Web query:
💡 Result: To install the CLI tool for Stellar and Soroban development, the current standard command is Citations:
🌐 Web query:
💡 Result: In the Stellar CLI, --network-passphrase is a standard option used to specify the network passphrase required for signing transactions [1][2][3]. It is categorized as an RPC-related option that is available for many commands that interact with the network [3]. Key details regarding this option include: Precedence and Behavior: 1. Named Network Priority: When you use the --network flag, the Stellar CLI resolves the network configuration from your on-disk settings [1][4]. Recent updates have established that a named network takes precedence over any --network-passphrase or --rpc-url provided via flags or environment variables [4]. 2. Overrides: If you do not use a named network, you can manually provide the --network-passphrase. For specific diagnostic commands, such as stellar network root-account, the --network-passphrase flag can be used to override other configured settings to derive root account keys [5]. 3. Configuration: While you can provide the passphrase as a flag, the recommended practice for general use is to configure named networks using the stellar network add command, which stores the network passphrase and RPC URL associated with an alias [3]. Usage: To use the option, append it to your command: stellar --network-passphrase "YOUR_PASSPHRASE" Note: Ensure you are using the correct passphrase for the intended network (e.g., the public network or a test network), as using an incorrect one will cause transaction authentication errors [6]. If you have a named network configured, you generally do not need to manually enter the passphrase [7][3]. Citations:
Align the Soroban/
🤖 Prompt for AI Agents |
||
|
|
||
| ## 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 | ||
| ``` | ||
|
Comment on lines
+22
to
+28
There was a problem hiding this comment. 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win 🧩 Analysis chain🏁 Script executed: #!/bin/bash
set -euo pipefail
echo "== docs/TROUBLESHOOTING.md lines =="
if [ -f docs/TROUBLESHOOTING.md ]; then
nl -ba docs/TROUBLESHOOTING.md | sed -n '1,80p'
else
echo "docs/TROUBLESHOOTING.md not found"
fi
echo
echo "== Find Freighter/network troubleshooting references =="
rg -n -i "Freighter|Connection rejected|not installed|connection request|locked|stellar network add|soroban-testnet.stellar.org|testnet" -S . --glob '!node_modules/**' --glob '!target/**' --glob '!dist/**' | head -200Repository: ritik4ever/stellar-goal-vault Length of output: 243 🏁 Script executed: #!/bin/sh
set -euo pipefail
echo "== docs/TROUBLESHOOTING.md lines =="
if [ -f docs/TROUBLESHOOTING.md ]; then
cat -n docs/TROUBLESHOOTING.md | sed -n '1,80p'
else
echo "docs/TROUBLESHOOTING.md not found"
fi
echo
echo "== Find Freighter/network troubleshooting references =="
grep -RIn -E "Freighter|Connection rejected|not installed|connection request|locked|stellar network add|soroban-testnet.stellar.org|testnet" . --exclude-dir=node_modules --exclude-dir=target --exclude-dir=dist | head -200 || trueRepository: ritik4ever/stellar-goal-vault Length of output: 50386 🏁 Script executed: #!/bin/sh
set -euo pipefail
echo "== docs/TROUBLESHOOTING.md lines 1-80 =="
awk '1==NR && NR<=80' docs/TROUBLESHOOTING.md | cat -n
echo
echo "== Target references in tracked/source files only =="
git ls-files | grep -E '(^docs/TROUBLESHOOTING\.md$|^docs/|^\.github/|src/|package.json|README\.md)' | while read -r f; do
grep -RInEi "Freighter|connection rejected|not installed|connection request|locked|stellar network add|soroban-testnet.stellar.org|testnet" "$f" 2>/dev/null || true
done | head -200Repository: ritik4ever/stellar-goal-vault Length of output: 12199 Make the Freighter troubleshooting steps match the listed causes. The listed causes include Freighter not being installed, connection requests being denied, or the extension being locked, but the fix only changes CLI network configuration. Reorder to cover browser-extension setup first (or add extension troubleshooting), and keep the 🤖 Prompt for AI Agents |
||
|
|
||
| ## 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 | ||
| ``` | ||
|
Comment on lines
+30
to
+37
There was a problem hiding this comment. 🎯 Functional Correctness | 🟠 Major | ⚡ Quick win Use the project’s actual frontend and backend ports in the CORS example. This hard-codes 🤖 Prompt for AI Agents |
||
|
|
||
| ## 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 | ||
| ``` | ||
|
Comment on lines
+39
to
+45
There was a problem hiding this comment. 🎯 Functional Correctness | 🟠 Major | ⚡ Quick win 🧩 Analysis chain🏁 Script executed: #!/bin/bash
set -euo pipefail
echo "== docs/TROUBLESHOOTING.md excerpt =="
if [ -f docs/TROUBLESHOOTING.md ]; then
cat -n docs/TROBLESHOOTING.md | sed -n '1,90p' || true
echo
cat -n docs/TROUBLESHOOTING.md | sed -n '1,90p' || true
fi
echo
echo "== README.md deployment/env references =="
if [ -f README.md ]; then
rg -n -i "CONTRACT_ID|contract deploy|soroban contract deploy|\\.env|backend/.env|environment" README.md -C 3 || true
fi
echo
echo "== backend env files =="
fd -a '^(\.env|.*\.env.*)$' backend . 2>/dev/null | sed 's#^\./##' | head -100
for f in $(fd '^(\.env|.*\.env.*)$' backend . 2>/dev/null | head -20); do
echo "--- $f"
sed -n '1,200p' "$f" | head -80 || true
done
echo
echo "== occurrences of generated contract file and CONTRACT_ID =="
rg -n "backend/\.env\.contract|#.*CONTRACT_ID|CONTRACT_ID=|contract deploy|contract-id|contract ID" -S . || trueRepository: ritik4ever/stellar-goal-vault Length of output: 12170 🏁 Script executed: #!/bin/bash
set -euo pipefail
echo "== scripts/deploy.sh relevant deployment flow =="
cat -n scripts/deploy.sh | sed -n '1,130p'
echo
echo "== DEPLOYMENT.md contract deployment section =="
cat -n DEPLOYMENT.md | sed -n '40,70p'
echo
echo "== local deploy output format evidence from scripts =="
python3 - <<'PY'
from pathlib import Path
scripts = [Path("scripts/deploy.sh"), Path("scripts/benchmark.sh")]
for p in scripts:
if p.exists():
text = p.read_text()
if "DEPLOY_OUTPUT=$(soroban contract deploy" in text or "export CONTRACT_ID=$(cat contracts/contract_id.txt)" in text:
print(f"\n-- {p} --")
for i,line in enumerate(text.splitlines(), 1):
if "contract deploy" in line or "DEPLOY_OUTPUT" in line or "grep -oE" in line or "CONTRACT_ID=$" in line or "CONTRACT_ID=" in line:
print(f"{i}: {line}")
PYRepository: ritik4ever/stellar-goal-vault Length of output: 5998 Document the actual deployment step. The project’s deployment script saves the contract ID to 🤖 Prompt for AI Agents |
||
|
|
||
| ## 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 | ||
| ``` | ||
|
Comment on lines
+56
to
+63
There was a problem hiding this comment. 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win Fix the Docker remediation wording. Change “Start the Docker service systemd” to “Start the Docker service with systemd.” 🤖 Prompt for AI Agents |
||
|
|
||
| ## 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"}' | ||
| ``` | ||
|
Comment on lines
+73
to
+79
There was a problem hiding this comment. 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win 🧩 Analysis chain🏁 Script executed: #!/bin/bash
set -euo pipefail
printf 'Locate troubleshooting file and reference documentation snippets:\n'
git ls-files | grep -E '(^|/)TROUBLESHOOTING\.md$|README|CONTRIBUTING' || true
if [ -f docs/TROUBLESHOOTING.md ]; then
sed -n '60,90p' docs/TROUBLESHOOTING.md | cat -n
fi
printf '\nSearch for getNetwork examples and curl diagnostics in repo:\n'
rg -n 'getNetwork|soroban-testnet|Timeout waiting for transaction|rpc|jsonrpc' docs README.md . 2>/dev/null | head -n 80 || trueRepository: ritik4ever/stellar-goal-vault Length of output: 50388 🌐 Web query:
💡 Result: To query the Stellar RPC (formerly Soroban-RPC) for network information using the getNetwork method, use an HTTP POST request with a Content-Type of application/json [1][2][3]. The method does not require any parameters [1][4]. Below is an example curl command. Replace <RPC_URL> with the endpoint of the Stellar RPC node you are accessing (e.g., a public provider or your own instance): curl --request POST \ --url <RPC_URL> \ --header 'Content-Type: application/json' \ --data '{ "jsonrpc": "2.0", "id": 1, "method": "getNetwork", "params": [] }' The Stellar RPC follows the JSON-RPC 2.0 specification [5][6]. The getNetwork method returns general information about the network, including the passphrase, the current protocol version, and an optional friendbot URL [1][2][4]. Top Results: [7][1][2][3][4] Citations:
🌐 Web query:
💡 Result: To query the getNetwork method on a Stellar RPC server, you must send a POST request with a Content-Type of application/json [1][2]. The request body must be a JSON-RPC 2.0 object specifying the method as getNetwork [1][2]. Below is a standard curl example for the getNetwork method: curl -X POST \ -H 'Content-Type: application/json' \ -d '{ "jsonrpc": "2.0", "id": 1, "method": "getNetwork" }' \ https://soroban-testnet.stellar.org Note that Stellar RPC was formerly known as Soroban-RPC [3]. When using this command, replace the URL (https://soroban-testnet.stellar.org) with the appropriate RPC endpoint you are targeting [3][1]. The getNetwork method does not require any additional parameters [1]. Citations:
Use the documented The example should include 🤖 Prompt for AI Agents |
||
|
|
||
| ## 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" | ||
| ``` | ||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
🩺 Stability & Availability | 🟡 Minor | ⚡ Quick win
Make the SQLite permission fix account for the actual backend user.
chmod 755/chmod 644only grants write access to the owner. If the backend runs as another user, SQLite still cannot create journal or WAL files. Document the required service-user ownership or provide a safechown/directory-creation example instead of implying these commands always resolve the error.🤖 Prompt for AI Agents