docs: add troubleshooting guide (Closes #426) - #490
Conversation
- Add docs/troubleshooting.md covering 12 common failures: wrong WASM target, missing Stellar CLI, Freighter network/config, RPC rate limits, insufficient testnet balance, AGENTS_NOT_CONFIGURED 503, contract build failures, Node.js version mismatch, missing env files, npm install errors, and cargo test issues - Each entry has symptom, cause, and fix - Link from README and CONTRIBUTING to the new guide
|
@Democodes-flash Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits. You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀 |
📝 WalkthroughWalkthroughAdds a troubleshooting guide covering common Lodestar setup and runtime failures, links it from the README and CONTRIBUTING.md, and provides commands and configuration examples for resolving documented issues. ChangesTroubleshooting documentation
Estimated code review effort: 2 (Simple) | ~10 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 5
🧹 Nitpick comments (1)
docs/troubleshooting.md (1)
130-135: 🩺 Stability & Availability | 🔵 TrivialAvoid promising a universal one-minute rate-limit reset.
RPC_URLmay point to SDF, a third-party provider, or a self-hosted endpoint, so reset windows and retry headers are provider-specific. Recommend honoringRetry-Afterwhen present and using exponential backoff instead of asserting a fixed one-minute interval. (developers.stellar.org)🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/troubleshooting.md` around lines 130 - 135, Update the “Wait and retry” guidance in the troubleshooting table to remove the fixed one-minute reset claim. Instruct users to honor the provider’s Retry-After value when available and otherwise retry with exponential backoff, while keeping the surrounding RPC mitigation strategies unchanged.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/troubleshooting.md`:
- Around line 20-22: Complete docs/troubleshooting.md after the existing
backend/.env example by closing its code fence and adding the missing headings
and content for “npm install or dependency errors” and “Cargo test fails with no
such command,” ensuring the TOC links resolve; alternatively remove those stale
TOC entries if the sections are not intended to be documented.
- Line 274: Update the RPC_URL example in the troubleshooting documentation to
use the valid Stellar Testnet endpoint https://soroban-testnet.stellar.org, or
replace it with the explicit placeholder https://<your-rpc-endpoint>.
- Around line 219-223: Update the troubleshooting step under “If still failing”
to remove the generic rm Cargo.lock and cargo generate-lockfile recommendation.
Instruct readers to preserve Cargo.lock, investigate the reported dependency
conflict, and use a targeted cargo update only when an update is necessary.
- Around line 107-118: Update the Freighter troubleshooting entry to remove all
references to the legacy window.freighter check and instead describe the
available connection state or isConnected() from `@stellar/freighter-api`. Retain
the installation and reload guidance, but make reloading conditional on the
browser needing to detect a newly installed extension.
- Around line 28-49: Update both WASM target troubleshooting sections to use the
current Soroban target wasm32v1-none instead of wasm32-unknown-unknown,
including the installation command and verification example. Set the stable Rust
toolchain before adding the target, and update the expected installed-target
output accordingly.
---
Nitpick comments:
In `@docs/troubleshooting.md`:
- Around line 130-135: Update the “Wait and retry” guidance in the
troubleshooting table to remove the fixed one-minute reset claim. Instruct users
to honor the provider’s Retry-After value when available and otherwise retry
with exponential backoff, while keeping the surrounding RPC mitigation
strategies unchanged.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID: e43761fc-7c4f-4c1e-b9cc-0f7749954ac5
📒 Files selected for processing (3)
CONTRIBUTING.mdREADME.mddocs/troubleshooting.md
| 10. [Missing or incorrect environment files](#10-missing-or-incorrect-environment-files) | ||
| 11. [npm install or dependency errors](#11-npm-install-or-dependency-errors) | ||
| 12. [Cargo test fails with no such command](#12-cargo-test-fails-with-no-such-command) |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
Complete the guide before merging.
The file ends inside the backend/.env code block at Line 275, so entries 11 and 12 from the TOC have no corresponding headings and their links are broken. This also explains the MD051 warnings on Lines 21-22. Add the remaining sections and close the code fence, or remove the stale TOC entries.
Also applies to: 259-275
🧰 Tools
🪛 markdownlint-cli2 (0.23.1)
[warning] 21-21: Link fragments should be valid
(MD051, link-fragments)
[warning] 22-22: Link fragments should be valid
(MD051, link-fragments)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/troubleshooting.md` around lines 20 - 22, Complete
docs/troubleshooting.md after the existing backend/.env example by closing its
code fence and adding the missing headings and content for “npm install or
dependency errors” and “Cargo test fails with no such command,” ensuring the TOC
links resolve; alternatively remove those stale TOC entries if the sections are
not intended to be documented.
Source: Linters/SAST tools
| **Symptom:** `cargo build` or `stellar contract build` fails with errors about `wasm32-unknown-unknown` not being found. | ||
|
|
||
| **Cause:** The Rust WASM target required to compile Soroban contracts is not installed. | ||
|
|
||
| **Fix:** | ||
|
|
||
| ```bash | ||
| rustup target add wasm32-unknown-unknown | ||
| ``` | ||
|
|
||
| Verify the target is installed: | ||
|
|
||
| ```bash | ||
| rustup target list --installed | grep wasm32 | ||
| # Expected output: wasm32-unknown-unknown | ||
| ``` | ||
|
|
||
| If the error persists after installing, ensure you are using a **stable** Rust toolchain (not nightly): | ||
|
|
||
| ```bash | ||
| rustup default stable | ||
| ``` |
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 =="
if [ -f docs/troubleshooting.md ]; then
sed -n '1,80p' docs/troubleshooting.md
echo "-- lines 190-218 --"
sed -n '190,218p' docs/troubleshooting.md
else
echo "missing docs/troubleshooting.md"
fi
echo
echo "== README wasm32 references =="
if git ls-files | grep -qiE '(^|/)README(\.md)?$'; then
git ls-files | grep -iE '(^|/)README(\.md)?$' | while read -r f; do
echo "-- $f --"
rg -n 'wasm32|stellar contract build|cargo contract' "$f" || true
done
else
echo "no README files"
fi
echo
echo "== Rust/Soroban target references in docs =="
rg -n 'wasm32-unknown-unknown|wasm32v1-none|rustup target add|stable|nightly' docs README.md docs 2>/dev/null || true
echo
echo "== stellar contract build target refs in tracked files =="
rg -n 'stellar contract build|--target|wasm32-unknown-unknown|wasm32v1-none|rustup target list' -S --glob '!target/**' --glob '!vendor/**' . || trueRepository: Stellar-Ecosystem/lodestar
Length of output: 156
🌐 Web query:
Stellar Soroban Rust WASM target wasm32v1-none rustup target add
💡 Result:
To develop Soroban smart contracts on Stellar, you must use the wasm32v1-none target [1][2]. Key technical details: Requirements The wasm32v1-none target is available starting with Rust version 1.84.0 [1][3]. You must have this version or higher installed to use it [3]. Installation You can add the target to your current Rust toolchain using the following command [3][4]: rustup target add wasm32v1-none Note that this target is installed per-toolchain; if you update your Rust version, you will need to reinstall it for the new toolchain [3]. Usage The recommended way to build contracts is using the Stellar CLI, which automatically handles the build target and configuration [1][5]: stellar contract build This command serves as a wrapper that performs the necessary operations equivalent to [5]: cargo build --target wasm32v1-none --release Why wasm32v1-none? The Soroban runtime supports only a specific subset of WebAssembly features [1]. While older versions of Soroban used the wasm32-unknown-unknown target, newer versions of Rust (1.82+) enable WASM features (such as reference-types and multi-value) that are incompatible with the Soroban environment [1][2]. The wasm32v1-none target restricts compilation to the WebAssembly 1.0 (MVP) subset, ensuring full compatibility with Soroban [1][6][7]. Use of wasm32-unknown-unknown on Rust 1.82 or newer is unsupported and will result in build errors [1][2].
Citations:
- 1: https://developers.stellar.org/docs/learn/fundamentals/contract-development/rust-dialect
- 2: https://github.com/stellar/rs-soroban-sdk/blob/main/README.md
- 3: https://developers.stellar.org/docs/build/smart-contracts/getting-started/setup
- 4: https://skills.stellar.org/skills/smart-contracts/SKILL.md
- 5: https://developers.stellar.org/docs/build/smart-contracts/getting-started/hello-world
- 6: https://dev-doc.rust-lang.org/stable/rustc/platform-support/wasm32v1-none.html
- 7: https://doc.rust-lang.org/stable/rustc/platform-support/wasm32-unknown-unknown.html
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf '== tracked docs/README files ==\n'
git ls-files '*README*' 'docs/troubleshooting.md' 'docs/*.md' | sort | sed -n '1,120p'
printf '\n== docs/troubleshooting.md first 49 lines ==\n'
sed -n '1,49p' docs/troubleshooting.md
printf '\n== docs/troubleshooting.md target references near lines 200-213 ==\n'
sed -n '200,213p' docs/troubleshooting.md
printf '\n== all wasm32/stellar contract build/rustup target references in tracked repo files (concise) ==\n'
rg -n 'wasm32-unknown-unknown|wasm32v1-none|stellar contract build|cargo build --target|--target |rustup target add|rustup default stable' -S --glob '!target/**' --glob '!node_modules/**' .Repository: Stellar-Ecosystem/lodestar
Length of output: 156
🏁 Script executed:
#!/bin/bash
set -u
printf 'Files:\n'
git ls-files '*' 2>/dev/null | sed -n '1,120p' || true
printf '\ndocs/troubleshooting.md first 60 lines:\n'
sed -n '1,60p' docs/troubleshooting.md 2>/dev/null || true
printf '\nTarget/build references (concise):\n'
if command -v rg >/dev/null 2>&1; then
rg -n 'wasm32-unknown-unknown|wasm32v1-none|stellar contract build|cargo build --target|--target |rustup target add|rustup default stable' -S . 2>/dev/null | sed -n '1,120p'
fiRepository: Stellar-Ecosystem/lodestar
Length of output: 156
Use the current Soroban WASM target.
Modern Soroban Rust tooling targets wasm32v1-none; installing wasm32-unknown-unknown leaves the required stable target unconfigured. Select Stable before adding the target, because rustup target add installs per-toolchain.
Suggested correction
+rustup default stable
+rustup target add wasm32v1-none
-rustup target add wasm32-unknown-unknown
...
-rustup default stableAlso applies to the same guidance repeated around lines 200-213.
📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| **Symptom:** `cargo build` or `stellar contract build` fails with errors about `wasm32-unknown-unknown` not being found. | |
| **Cause:** The Rust WASM target required to compile Soroban contracts is not installed. | |
| **Fix:** | |
| ```bash | |
| rustup target add wasm32-unknown-unknown | |
| ``` | |
| Verify the target is installed: | |
| ```bash | |
| rustup target list --installed | grep wasm32 | |
| # Expected output: wasm32-unknown-unknown | |
| ``` | |
| If the error persists after installing, ensure you are using a **stable** Rust toolchain (not nightly): | |
| ```bash | |
| rustup default stable | |
| ``` | |
| **Symptom:** `cargo build` or `stellar contract build` fails with errors about `wasm32-unknown-unknown` not being found. | |
| **Cause:** The Rust WASM target required to compile Soroban contracts is not installed. | |
| **Fix:** | |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/troubleshooting.md` around lines 28 - 49, Update both WASM target
troubleshooting sections to use the current Soroban target wasm32v1-none instead
of wasm32-unknown-unknown, including the installation command and verification
example. Set the stable Rust toolchain before adding the target, and update the
expected installed-target output accordingly.
| **Symptom:** The frontend displays "Freighter not detected" or `window.freighter` is `undefined`. Clicking "Connect Wallet" does nothing. | ||
|
|
||
| **Cause:** The Freighter extension is not installed, is disabled, or the page needs to be reloaded after installation. | ||
|
|
||
| **Fix:** | ||
|
|
||
| 1. Install [Freighter](https://freighter.app/) from the Chrome Web Store | ||
| 2. Create or import a wallet and fund it with Testnet Lumens (see [issue 6](#6-insufficient-testnet-balance)) | ||
| 3. **Reload** the Lodestar page (a simple refresh is required after installing) | ||
| 4. If it still fails, check browser console (`F12` → Console) for errors | ||
|
|
||
| **Browser compatibility:** Freighter supports Chrome, Brave, Edge, and Firefox. Safari support is limited. |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== files =="
git ls-files | sed -n '1,200p'
echo "== docs troub =="
if [ -f docs/troubleshooting.md ]; then
sed -n '90,125p' docs/troubleshooting.md
fi
echo "== freighter/api mentions =="
rg -n "freighter|Freight|window\.freighter|`@stellar/freighter-api`|isConnected|requestAccess|getNetwork" . -S || true
echo "== package snippets =="
fd -i 'package\.json$' . -x sh -c 'echo "--- $1"; if grep -qE "freighter|stellar|`@stellar`" "$1"; then sed -n "1,220p" "$1"; fi' sh {}Repository: Stellar-Ecosystem/lodestar
Length of output: 18507
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== frontend freighter implementation =="
sed -n '1,120p' frontend/lib/freighter.ts
echo "== frontend wallet implementation excerpt =="
sed -n '1,120p' frontend/lib/wallet.ts
echo "== wallet connect components excerpt =="
sed -n '1,140p' frontend/components/WalletContext.tsx
sed -n '1,130p' frontend/components/WalletPickerModal.tsx
echo "== package-lock freighter api entry =="
python3 - <<'PY'
import json
from pathlib import Path
p=Path('frontend/package-lock.json')
data=json.loads(p.read_text())
for key in ['node_modules/@stellar/freighter-api','frontend/node_modules/@stellar/freighter-api']:
if key in data.get('packages',{}):
print(key, data['packages'][key].get('version'), data['packages'][key].get('resolved'), data['packages'].get(key,{}).get('dependencies'))
PYRepository: Stellar-Ecosystem/lodestar
Length of output: 12548
🌐 Web query:
@stellar/freighter-api 3.0.0 isConnected requestAccess getNetwork window.freighter
💡 Result:
In the @stellar/freighter-api library, functions like isConnected, requestAccess, and getNetwork are provided as named exports to facilitate communication with the Freighter extension [1][2][3]. While older versions or specific implementations sometimes referenced window.freighter or window.freighterApi, current best practices involve importing these methods directly from the package [1][3]. isConnected Checks if the Freighter extension is installed in the browser [4][3]. It returns a promise that resolves to an object containing the boolean isConnected status [3]. It should be checked before attempting to access other extension features [3]. requestAccess Prompts the user to authorize the dApp and returns their public key (address) in a single step [4][3]. It is the recommended method for connecting to the wallet [4][3]. If the user has already authorized the dApp, it returns the address immediately without an additional prompt [3]. getNetwork Retrieves the name and passphrase of the network currently selected in the Freighter extension [5]. window.freighter / window.freighterApi Historically, some integrations accessed the API directly via global objects like window.freighter or window.freighterApi [1][6]. However, official documentation now emphasizes installing and importing the @stellar/freighter-api package for type safety and better integration [1][7]. Developers who need to simulate the environment for testing purposes sometimes manually inject a window.freighter object into the test browser [2]. Integration Note: Always ensure the extension is detected via isConnected before calling methods that require user interaction, such as requestAccess [3].
Citations:
- 1: https://docs.freighter.app/extension-freighter-api/installation
- 2: https://github.com/Nova-reward/Nova-Rewards/blob/main/docs/stellar/freighter-guide.md
- 3: https://github.com/stellar/freighter-developer-docs/blob/main/extension/connecting.md
- 4: https://docs.freighter.app/extension-freighter-api/connecting
- 5: https://docs.freighter.app/extension-freighter-api/reading-data
- 6: https://stellar.stackexchange.com/questions/5916/get-public-key-variable-from-freighter-wallet
- 7: https://docs.freighter.app/docs/
🌐 Web query:
site:freighter.app @stellar/freighter-api isConnected requestAccess window.freighter
💡 Result:
The @stellar/freighter-api library is the recommended way to integrate the Freighter wallet into web applications [1]. It provides a standardized interface for interacting with the Freighter browser extension [2][1]. Key methods: isConnected This method checks whether the Freighter extension is installed in the user's browser [2]. It returns a promise that resolves to an object containing the boolean property isConnected [2]. It is best practice to always call isConnected before performing other operations to ensure the extension is available [2]. requestAccess This method prompts the user to authorize your dApp and returns their public key [2]. It is the recommended approach for establishing a connection, as it combines authorization and data retrieval into a single step [2]. If the user has already authorized your application, the public key is returned without an additional prompt [2]. Window Object The Freighter API also injects an object into the window, typically accessed via window.freighterApi [3]. While the @stellar/freighter-api library simplifies imports, you can interact with the API directly through this global object if necessary, for example: const { address } = await window.freighterApi.requestAccess; [3] Integration Summary 1. Installation: Install the library via npm or yarn: npm install @stellar/freighter-api [3][4]. 2. Usage: Import the necessary functions and ensure you verify the extension's presence before proceeding [2]. Example: import { isConnected, requestAccess } from "@stellar/freighter-api"; async function connect { const { isConnected: installed } = await isConnected; if (!installed) { console.error("Freighter is not installed"); return; } const { address, error } = await requestAccess; if (error) { console.error("Access denied:", error.message); } else { console.log("Connected address:", address); } } [2]
Citations:
- 1: https://docs.freighter.app/
- 2: https://docs.freighter.app/extension-freighter-api/connecting
- 3: https://docs.freighter.app/extension-freighter-api/installation
- 4: https://docs.freighter.app/docs/
Remove the legacy window.freighter troubleshooting check.
The symptom and fix should reference the available connection state or isConnected() from @stellar/freighter-api instead of window.freighter, which is not the API the frontend imports or exposes. Include a small actionable step for reloading only when the browser needs to discover the newly installed extension.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/troubleshooting.md` around lines 107 - 118, Update the Freighter
troubleshooting entry to remove all references to the legacy window.freighter
check and instead describe the available connection state or isConnected() from
`@stellar/freighter-api`. Retain the installation and reload guidance, but make
reloading conditional on the browser needing to detect a newly installed
extension.
| # 4. If still failing, delete Cargo.lock and retry | ||
| rm Cargo.lock | ||
| cargo generate-lockfile | ||
| stellar contract build | ||
| ``` |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
Do not recommend deleting Cargo.lock as a generic repair.
Removing the lockfile and regenerating it can upgrade the entire dependency graph and introduce unrelated incompatibilities. Prefer preserving it, checking the reported dependency conflict, and using a targeted cargo update when an update is actually required. (doc.rust-lang.org)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/troubleshooting.md` around lines 219 - 223, Update the troubleshooting
step under “If still failing” to remove the generic rm Cargo.lock and cargo
generate-lockfile recommendation. Instruct readers to preserve Cargo.lock,
investigate the reported dependency conflict, and use a targeted cargo update
only when an update is necessary.
| ```env | ||
| PORT=3001 | ||
| DATABASE_URL=postgresql://... | ||
| RPC_URL=https://soroban-testnet |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
Use a valid default RPC endpoint.
https://soroban-testnet is incomplete and will not connect to Stellar Testnet. The public Testnet RPC endpoint is https://soroban-testnet.stellar.org; use that value or an explicit placeholder such as https://<your-rpc-endpoint>. (developers.stellar.org)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/troubleshooting.md` at line 274, Update the RPC_URL example in the
troubleshooting documentation to use the valid Stellar Testnet endpoint
https://soroban-testnet.stellar.org, or replace it with the explicit placeholder
https://<your-rpc-endpoint>.
|
Hi @Democodes-flash, This PR could not be merged because it has merge conflicts with the target branch. Please resolve the merge conflicts, push the updated changes, and the PR can be reviewed and merged. Thank you! |
2 participants
Overview
Adds a comprehensive troubleshooting guide covering 12 common failures that new contributors and users encounter when setting up or running Lodestar. Each entry follows a consistent symptom → cause → fix format. The guide is linked from both the README and CONTRIBUTING for discoverability.
Related Issue
Closes #426
Changes
[ADD]
docs/troubleshooting.md— 12 troubleshooting entries:wasm32-unknown-unknownnot installedstellarcommand not foundop_underfundederrorsAGENT_SECRET_KEYenv var.envfiles across backend/frontend/agent/contractnode-gypfailures[UPDATE]
README.md— Added "Troubleshooting" section with link to the guide[UPDATE]
CONTRIBUTING.md— Added "Troubleshooting" section with link to the guideAcceptance Criteria
Testing
Summary by CodeRabbit