Troubleshooting guide#811
Troubleshooting guide#811leofelix077 wants to merge 3 commits intolf-add-freighter-mobile-best-practices-skillfrom
Conversation
…ry issues Android Studio sometimes doesn't apply RAM changes to existing AVDs reliably; recreating the emulator is the definitive fix.
There was a problem hiding this comment.
Pull request overview
Adds a centralized troubleshooting reference for common Freighter Mobile dev environment, build, testing, and dependency issues, and links it from the contributor/agent entry-point doc.
Changes:
- Introduce
docs/troubleshooting-guide.mdwith setup/build/test/dependency troubleshooting steps and known gotchas. - Add a “Troubleshooting” row in
AGENTS.mdto surface the new guide alongside other best-practices entry points.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 4 comments.
| File | Description |
|---|---|
| docs/troubleshooting-guide.md | New troubleshooting guide covering common local dev, CI, and dependency issues. |
| AGENTS.md | Adds a pointer to the troubleshooting guide in the “Best Practices Entry Points” table. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| **Solution:** | ||
|
|
||
| ```bash | ||
| yarn r-install # Full reset: cleans node_modules, reinstalls everything |
There was a problem hiding this comment.
yarn r-install is described as a full reset that "reinstalls everything", but the actual script is yarn reset-env && yarn rebuild freighter-mobile. reset-env deletes node_modules and prints that you must run yarn install afterwards, so r-install as written does not reinstall dependencies and is likely to fail/leave the repo unusable.
Suggestion: either update the docs to reflect the real steps (e.g., run reset-env then yarn install), or update the r-install script to perform the install step as part of the reset.
| yarn r-install # Full reset: cleans node_modules, reinstalls everything | |
| yarn reset-env # Clears node_modules and other generated state | |
| yarn install # Reinstall JavaScript dependencies | |
| yarn rebuild freighter-mobile # Rebuild the app package if needed |
| > **Warning:** Do not run `pod deintegrate` — it strips the entire Xcode project | ||
| > integration. Clean cache + reinstall is sufficient. |
There was a problem hiding this comment.
The "Do not run pod deintegrate" warning conflicts with existing guidance in docs/skills/freighter-mobile-best-practices/references/dependencies.md, which recommends pod deintegrate as part of the CocoaPods clean/reinstall flow. This is likely to confuse contributors.
Suggestion: clarify when pod deintegrate is appropriate vs harmful for this repo, or align this troubleshooting section with the best-practices doc (and update the other doc if needed).
| > **Warning:** Do not run `pod deintegrate` — it strips the entire Xcode project | |
| > integration. Clean cache + reinstall is sufficient. | |
| > **Note:** For routine `pod install` failures like version conflicts or missing | |
| > specs, do **not** start with `pod deintegrate`; clean cache + reinstall is | |
| > usually sufficient. Use `pod deintegrate` only if CocoaPods/Xcode project | |
| > integration is actually broken, or if you are intentionally following the | |
| > full CocoaPods clean/reinstall flow documented in the dependency | |
| > best-practices guide. |
| > Code Quality Tools > ESLint → "Automatic ESLint configuration". | ||
| 3. **Validate manually:** | ||
| ```bash | ||
| npx eslint src/components/sds/Button.tsx |
There was a problem hiding this comment.
The manual ESLint validation command points to src/components/sds/Button.tsx, but this repo's SDS Button component lives at src/components/sds/Button/index.tsx (and imports use components/sds/Button). As written, the example command will fail with a "file not found"/no matches error.
Suggestion: update the example to reference a file path that exists in this repo (e.g., src/components/sds/Button/index.tsx).
| npx eslint src/components/sds/Button.tsx | |
| npx eslint src/components/sds/Button/index.tsx |
| (1.16.2) is higher than the version of the current executable." | ||
|
|
||
| **Solution:** Ensure all team members use the same CocoaPods version: | ||
|
|
||
| ```bash | ||
| gem install cocoapods -v 1.16.2 # Match the lockfile version |
There was a problem hiding this comment.
The CocoaPods lockfile mismatch example hard-codes CocoaPods version 1.16.2, but the current ios/Podfile.lock indicates it was generated with CocoaPods 1.15.2 (COCOAPODS: 1.15.2).
Suggestion: update the version in this section to match the lockfile (or re-generate/commit Podfile.lock with 1.16.2 if that is now the team standard).
| (1.16.2) is higher than the version of the current executable." | |
| **Solution:** Ensure all team members use the same CocoaPods version: | |
| ```bash | |
| gem install cocoapods -v 1.16.2 # Match the lockfile version | |
| (1.15.2) is higher than the version of the current executable." | |
| **Solution:** Ensure all team members use the same CocoaPods version: | |
| ```bash | |
| gem install cocoapods -v 1.15.2 # Match the lockfile version |
No description provided.