NEW troubleshooting section (SetUp)
Summary: Restyle of Trobleshooting, which involved changes to sidebar.js and splitting up the previous troubleshooting page into five separate pages. Reviewed By: lblasa Differential Revision: D36282539 fbshipit-source-id: e60834e2b4d98b70b23bb11309c3438d85e4de0e
This commit is contained in:
Kevin Strider
committed by
Facebook GitHub Bot
Facebook GitHub Bot
parent
6cdda85ec9
commit
0b16f3a031
@@ -36,7 +36,7 @@ export function NoDevices() {
|
||||
<Text>
|
||||
Start a fresh emulator <RocketOutlined onClick={onLaunchEmulator} />{' '}
|
||||
or check the{' '}
|
||||
<Link href="https://fbflipper.com/docs/troubleshooting">
|
||||
<Link href="https://fbflipper.com/docs/getting-started/troubleshooting/troubleshooting">
|
||||
troubleshooting guide
|
||||
</Link>
|
||||
.
|
||||
|
||||
@@ -139,6 +139,6 @@ Above, the Layout Inspector plugin has been added to get you started. See the <L
|
||||
|
||||
For examples of integrating other plugins, take a look at the sample apps in the [GitHub repo](https://github.com/facebook/flipper).
|
||||
|
||||
## Questions or issues
|
||||
## Isues or questions
|
||||
|
||||
If you have any questions or issues, refer to the <Link to={useBaseUrl("/docs/troubleshooting")}>troubleshooting</Link> page, or post the details on the [Flipper Support](https://fb.workplace.com/groups/flippersupport) Workplace group.
|
||||
If you encounter any issues or have any questions, refer to the [Troubleshooting](troubleshooting/troubleshooting.mdx) section.
|
||||
|
||||
@@ -55,5 +55,5 @@ If you are hacking a JS app, you should be good to go without any extra dependen
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
If you run into problems, take a look at the [troubleshooting](../troubleshooting.mdx) page.
|
||||
If you run into problems, take a look at the [troubleshooting](troubleshooting/troubleshooting.mdx) section.
|
||||
Failing that, check <OssOnly>[GitHub Issues](https://github.com/facebook/flipper/issues).</OssOnly><FbInternalOnly>the [Workplace group](https://fb.workplace.com/groups/230455004101832/).</FbInternalOnly>
|
||||
|
||||
@@ -152,6 +152,6 @@ class AppDelegate: UIResponder, UIApplicationDelegate {
|
||||
Finally, you need to add plugins to your Flipper client. The Layout Inspector plugin is shown above to get you started.
|
||||
See <Link to={useBaseUrl("/docs/setup/plugins/network")}>Network Plugin</Link> and [Layoutj Inspector Plugin](https://www.internalfb.com/intern/staticdocs/flipper/docs/features/plugins/inspector/) for information on how to add them and enable Litho or ComponentKit support. You can check the sample apps in the [GitHub repo](https://github.com/facebook/flipper) for examples of integrating other plugins.
|
||||
|
||||
## Questions or issues
|
||||
## Isues or questions
|
||||
|
||||
If you have any questions or issues, refer to the <Link to={useBaseUrl("/docs/troubleshooting")}>troubleshooting</Link> page, or post the details on the [Flipper Support](https://fb.workplace.com/groups/flippersupport) Workplace group.
|
||||
If you encounter any issues or have any questions, refer to the [Troubleshooting](troubleshooting/troubleshooting.mdx) section.
|
||||
|
||||
@@ -193,9 +193,9 @@ class AppDelegate: UIResponder, UIApplicationDelegate {
|
||||
|
||||
Lastly, open the Flipper desktop app, and run `yarn ios` in your terminal.
|
||||
|
||||
## Troubleshooting
|
||||
## Isues or questions
|
||||
|
||||
See the <Link to={useBaseUrl("/docs/troubleshooting")}>troubleshooting page</Link> for help with known problems.
|
||||
If you encounter any issues or have any questions, refer to the [Troubleshooting](troubleshooting/troubleshooting.mdx) section.
|
||||
|
||||
## Further Steps
|
||||
|
||||
|
||||
63
docs/getting-started/troubleshooting/android.mdx
Normal file
63
docs/getting-started/troubleshooting/android.mdx
Normal file
@@ -0,0 +1,63 @@
|
||||
---
|
||||
id: android
|
||||
title: Troubleshooting Android Issues
|
||||
sidebar_label: Android Issues
|
||||
custom_edit_url: https://www.internalfb.com/intern/diffusion/FBS/browsefile/master/xplat/sonar/docs/android.mdx
|
||||
---
|
||||
|
||||
Flipper is a work in progress and issues may occur. This page contains known issues associated with the Android platform and provides steps you can take to try to resolve them.
|
||||
|
||||
## Exception from call site #4 bootstrap method
|
||||
|
||||
Build error after including the Flipper dependency:
|
||||
|
||||
```
|
||||
Exception from call site #4 bootstrap method
|
||||
```
|
||||
|
||||
This can happen because we include [OkHttp3](https://github.com/square/okhttp/issues/4597#issuecomment-461204144) as dependency which makes use of Java 8 features. There are two ways of dealing with this:
|
||||
|
||||
**Enable Java 8 support**
|
||||
|
||||
Add this to your Gradle config:
|
||||
|
||||
```groovy
|
||||
android {
|
||||
compileOptions {
|
||||
targetCompatibility = "8"
|
||||
sourceCompatibility = "8"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Exclude the OkHttp3 dependency**
|
||||
|
||||
Alternatively, if you don't plan on making use of OkHttp, you can exclude the dependency from the build entirely:
|
||||
|
||||
```
|
||||
debugImplementation('com.facebook.flipper:flipper:*') {
|
||||
exclude group: 'com.squareup.okhttp3'
|
||||
}
|
||||
```
|
||||
|
||||
## Duplicate class `com.facebook.jni.*`
|
||||
|
||||
This can occur when mixing different versions of [FBJNI](https://github.com/facebookincubator/fbjni),
|
||||
a library we use to interact with native C++ code.
|
||||
|
||||
Speficially, this can happen when the versions `0.0.x` and `0.1.x` are mixed. Version `0.1.0` of FBJNI
|
||||
switched to using [Google Prefab](https://google.github.io/prefab/) for distributing native artifacts,
|
||||
which made the split into combined, "java-only" and "header" packages redundant and only requires
|
||||
a single dependency in your projects.
|
||||
|
||||
When including both "fbjni-java-only:0.0.1" and "fbjni:0.1.0" in one project, you will now
|
||||
duplicate class errors during the build process. You must ensure that only one of the two
|
||||
versions is used in your entire dependency tree. Start by looking at `./gradlew :myapp:dependencies`
|
||||
to see where the different version requirements come from. Then exclude the FBJNI dependency from
|
||||
one of them, e.g.
|
||||
|
||||
```groovy
|
||||
implementation("com.facebook.react:react-native:+") {
|
||||
exclude group:'com.facebook.fbjni'
|
||||
}
|
||||
```
|
||||
146
docs/getting-started/troubleshooting/general-issues.mdx
Normal file
146
docs/getting-started/troubleshooting/general-issues.mdx
Normal file
@@ -0,0 +1,146 @@
|
||||
---
|
||||
id: general-issues
|
||||
title: General Issues
|
||||
sidebar_label: General Issues
|
||||
custom_edit_url: https://www.internalfb.com/intern/diffusion/FBS/browsefile/master/xplat/sonar/docs/general-issues.mdx
|
||||
---
|
||||
|
||||
:::note
|
||||
There is a public build of Flipper and an internal one. The internal app provides more plugins and earlier access to features, so you should use it.
|
||||
|
||||
The latest version of Flipper also has an interactive, self-navigating troubleshooting guide button. Please check that out to help you troubleshoot issues specific to your case.
|
||||
:::
|
||||
|
||||
## Internal Meta releases
|
||||
|
||||
The internal build of Flipper has some extra features that the open source one doesn't. To get the latest version, please install Flipper from the Managed Software Centre rather than the Flipper website.
|
||||
|
||||
## Up to date mobile app and Flipper version
|
||||
|
||||
Occasionally there are breaking protocol changes, so if you're having trouble, make sure the app you're building is rebased relatively recently onto stable and that the flipper version is also up to date.
|
||||
|
||||
## In-app diagnostics
|
||||
|
||||
### Android
|
||||
|
||||
Run the following:
|
||||
|
||||
```bash
|
||||
adb shell am start -n <APP_PACKAGE>/com.facebook.flipper.android.diagnostics.FlipperDiagnosticActivity
|
||||
```
|
||||
|
||||
For example, for an FB4A debug build, run:
|
||||
`adb shell am start -n com.facebook.wakizashi/com.facebook.flipper.android.diagnostics.FlipperDiagnosticActivity`.
|
||||
|
||||
Or open Flipper Diagnostics from the internal settings, which is available in some apps.
|
||||
|
||||
### iOS
|
||||
|
||||
Diagnostics have been added to the Internal Settings of the biggest apps.
|
||||
|
||||
Navigate to `Internal settings > Troubleshooting Flipper (Sonar)`
|
||||
|
||||
## iOS App in physical device not connecting to Flipper? idb permission issues?
|
||||
|
||||
This may be because the app you're trying to connect to is signed by an enterprise certificate. If you've downloaded the builds from Mobile Home or the Mobile Builds Plugin, then the app is signed by enterprise certificates. If the app is built locally, then it's signed by developer certificates and idb can access the app's sandbox.
|
||||
|
||||
Flipper does not support all the apps signed by enterprise certificates. Have a look at the following matrix to see, if your app is supported.
|
||||
|
||||
<table class="ios-support-matrix">
|
||||
<thead>
|
||||
<tr>
|
||||
<th></th>
|
||||
<th>Built Locally</th>
|
||||
<th>Mobile Home/Boilerroom builds/builds signed by enterprise certificates</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td>FB</td>
|
||||
<td class="supported"> </td>
|
||||
<td class="supported">Supported only by WWW cert exchange mode</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>IG</td>
|
||||
<td class="supported"></td>
|
||||
<td class="supported">Supported only by WWW cert exchange mode</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Messenger</td>
|
||||
<td class="supported"> </td>
|
||||
<td class="not-supported"> Not Supported</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Workplace</td>
|
||||
<td class="supported"> </td>
|
||||
<td class="not-supported"> Not Supported</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Workchat</td>
|
||||
<td class="supported"> </td>
|
||||
<td class="not-supported"> Not Supported</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Other iOS Apps</td>
|
||||
<td class="supported">Supported if Flipper SDK is integrated </td>
|
||||
<td class="not-supported"> Not Supported</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
In the above table:
|
||||
|
||||
* If your app is supported and the cell contains 'Supported only by WWW certificate exchange', then you will have to do the following:
|
||||
|
||||
* Ensure both Flipper and your mobile app are connected to Lighthouse.
|
||||
* In your mobile app, go to Internal Setting -> "Flipper Certificate Exchange", enable the toggle.
|
||||
* Your app will get connected now.
|
||||
|
||||
* If your app falls in the red zone, then you can enable the WWW certificate exchange for your app by following [this guide](/docs/fb/www-certificate-exchange).
|
||||
|
||||
## Physical SELinux-based device (think Portal) cannot connect
|
||||
|
||||
A definitive sign of the issue is if you see `avc: denied ...` in the device logs.
|
||||
|
||||
Try running the following:
|
||||
|
||||
```bash
|
||||
adb root
|
||||
adb shell setenforce 0
|
||||
```
|
||||
|
||||
## Only Logs, Layout and Network plugins showing
|
||||
|
||||
You're probably using the public build of Flipper. Instead, download the internal one from [Flipper Support](https://fb.facebook.com/groups/230455004101832/permalink/470961366717860/).
|
||||
|
||||
## iOS Simulator not shown in device list
|
||||
|
||||
Ensure that `ps aux | grep CoreSimulator` and `xcode-select -p` have the same Xcode version. If not, update the xcode version by sudo `xcode-select --switch <Path to xcode>`
|
||||
|
||||
If it still doesn't function, then post the details in the [Flipper Support](https://fb.facebook.com/groups/230455004101832/) Workplace group.
|
||||
|
||||
## Launcher can't download
|
||||
|
||||
Flipper downloads need to happen either while on Lighthouse or a VPN connection. To check the status of your connection, visit [bunny i vlaninfo](https://www.internalfb.com/intern/vlaninfo).
|
||||
|
||||
## Prefetch unsupported
|
||||
|
||||
You may see a message on your terminal about prefetch being unsupported. This means you downloaded Flipper manually and moved it into your `/Applications/` folder. Installing Flipper this way is unsupported. Not
|
||||
only may it be missing important plugins for your work at Meta but will also never receive updates and is likely to stop working at some point in the future as the apps receive updates.
|
||||
|
||||
Please manually remove `/Applications/Flipper.app` and reinstall Flipper from the [Managed Software Center](https://www.internalfb.com/intern/wiki/Client_Platform_Engineering/Users/Managed_Software_Center_(MSC)/).
|
||||
|
||||
## Android app remains in status 'Currently connecting...' status forever
|
||||
|
||||
Verify that the application has the right permissions to read the certificates that are used to connect to Flipper (see this Flipper Support [thread](https://fb.workplace.com/groups/flippersupport/permalink/1062569534223704/)).
|
||||
|
||||
Try running `adb root && adb shell setenforce 0` as a workaround.
|
||||
|
||||
## React Native plugins do not show up for my on-demand running mobile app
|
||||
|
||||
1. Make sure that the 'JavaScript bundler' is running in the 'React Native' section of the Mobile Development plugin.
|
||||
2. Take the following steps to ensure that the tunnel for port 8081 is connected in the 'Port Tunnels' section as it might incorrectly report that it's connected (see the following [bug](https://www.internalfb.com/intern/bugs/user/100003692117643/)):
|
||||
|
||||
* Press connect.
|
||||
* Perform DUO authentication.
|
||||
* Verify that the terminal reports that the tunnel was created successfully. If it reports 'cannot listen to port 8081', make sure to kill any local processes on that port and try again: `kill -9 $(lsof -t -i tcp:8081)`.
|
||||
82
docs/getting-started/troubleshooting/mac-desktop-app.mdx
Normal file
82
docs/getting-started/troubleshooting/mac-desktop-app.mdx
Normal file
@@ -0,0 +1,82 @@
|
||||
---
|
||||
id: mac-desktop-app
|
||||
title: Troubleshooting Mac Desktop App Issues
|
||||
sidebar_label: Mac Desktop App Issues
|
||||
custom_edit_url: https://www.internalfb.com/intern/diffusion/FBS/browsefile/master/xplat/sonar/docs/mac-desktop-app.mdx
|
||||
---
|
||||
|
||||
Flipper is a work in progress and issues may occur. This page contains known issues associated with the Mac desktop apps and provides steps you can take to try to resolve them.
|
||||
|
||||
## Flipper won't launch on Mac
|
||||
|
||||
* If the window is appearing, try opening the Chrome DevTools within Flipper. To do so, from the View menu select 'Toggle Developer Tools' or press CMD+Option+I and check if there are any errors on the console.
|
||||
* Launch Flipper from the command line using `/Applications/Flipper.app/Contents/MacOS/Flipper`. This should give you some logs, that might be helpful when debugging.
|
||||
* Delete `~/.flipper` and try relaunching Flipper.
|
||||
* Delete Flipper from your applications folder and redownload [Flipper](https://www.facebook.com/fbflipper/public/mac).
|
||||
* If you're using `yarn start` to run from source, make sure all dependencies are installed correctly by running yarn install.
|
||||
|
||||
## Flipper shows weird render artifacts
|
||||
|
||||
This is a long standing MacOS + Electron issue outside our control. In general, restarting your computer fixes the problem.
|
||||
For a quick, temporarily work around start Flipper with hardware acceleration disabled. Please note that this will consume a lot of CPU: `FLIPPER_DISABLE_GPU=1 open -a Flipper`.
|
||||
|
||||
## iOS Simulator fails to connect with error "Failed to find device..."
|
||||
|
||||
Try executing `idb kill` and restarting Flipper. See [this comment](https://fb.workplace.com/groups/flippersupport/posts/1288502608297061/?comment_id=1290222721458383&reply_comment_id=1290374518109870) for details.
|
||||
|
||||
## iOS Simulator missing from devices dropdown
|
||||
|
||||
* Check that `xcode-select -p` shows the same XCode version that you're using. If not, see xcode-select for how to select the correct version.
|
||||
|
||||
## iOS physical device not showing up
|
||||
|
||||
Make sure [`idb`](https://fbidb.io/docs/installation) is installed and configured in the Flipper settings.
|
||||
|
||||
## App on physical iOS device stuck in 'connecting...' state
|
||||
|
||||
Make sure you are building and installing the application from source.
|
||||
|
||||
## No plugins showing up for your device
|
||||
|
||||
* Check your device isn't on the list of [known incompatibilities](#known-incompatibilities).
|
||||
* Make sure your version of Flipper is up to date.
|
||||
* Make sure the mobile SDK you are using is relatively recent (<1 month old).
|
||||
* Open Chrome dev tools within Flipper. To do so, from the View menu select Toggle Developer Tools or press CMD+Option+I and check if there are any errors on the console.
|
||||
* Delete `~/.flipper`.
|
||||
* **Uninstall** and reinstall the mobile app.
|
||||
* Make sure the time and date are set correctly on your mobile device and desktop computer.
|
||||
* If no app plugins are showing up, there may be a connectivity issue between Flipper and your app. Check [connection issues](#connection-issues) to see if anything is failing.
|
||||
|
||||
<OssOnly>
|
||||
|
||||
## Connection Issues
|
||||
The Flipper SDK includes an in-app connection diagnostics screen to help you diagnose problems.
|
||||
|
||||
### Android
|
||||
|
||||
Replace `<APP_PACKAGE>` below with the package name of your app, for example, such as `com.facebook.flipper.sample`.
|
||||
|
||||
On a terminal, run the following:
|
||||
|
||||
```bash
|
||||
adb shell am start -n <APP_PACKAGE>/com.facebook.flipper.android.diagnostics.FlipperDiagnosticActivity
|
||||
```
|
||||
|
||||
This will only work if you added `FlipperDiagnosticActivity` to your `AndroidManifest.xml`. See [getting started](./getting-started/android-native.mdx#diagnostics) for help.
|
||||
|
||||
### iOS
|
||||
|
||||
You'll need to manually add this [ViewController](https://github.com/facebook/flipper/blob/main/iOS/FlipperKit/FlipperDiagnosticsViewController.m) to your app to see the in-app diagnostics.
|
||||
|
||||
</OssOnly>
|
||||
|
||||
## Known Incompatibilities
|
||||
|
||||
The following devices are known to be incompatible or face issues with Flipper:
|
||||
|
||||
* Some Samsung devices ([Tracking Issue](https://github.com/facebook/flipper/issues/92)).
|
||||
* Genymotion emulators on Android 8+ are reported to have issues.
|
||||
|
||||
## File an Issue
|
||||
|
||||
Still not working? File an issue on [GitHub](https://github.com/facebook/flipper/issues) with the chrome DevTools logs and the output from the diagnostics screen, if relevant.
|
||||
15
docs/getting-started/troubleshooting/portal.mdx
Normal file
15
docs/getting-started/troubleshooting/portal.mdx
Normal file
@@ -0,0 +1,15 @@
|
||||
---
|
||||
id: portal
|
||||
title: Troubleshooting Portal Issues
|
||||
sidebar_label: Portal Issues
|
||||
custom_edit_url: https://www.internalfb.com/intern/diffusion/FBS/browsefile/master/xplat/sonar/docs/portal.mdx
|
||||
---
|
||||
|
||||
We've found that some portal devices running Android 10 fail to connect to Flipper by default.
|
||||
|
||||
You can work around this by running the following on a terminal:
|
||||
|
||||
```
|
||||
adb root
|
||||
adb shell setenforce 0
|
||||
```
|
||||
149
docs/getting-started/troubleshooting/react-native.mdx
Normal file
149
docs/getting-started/troubleshooting/react-native.mdx
Normal file
@@ -0,0 +1,149 @@
|
||||
---
|
||||
id: react-native
|
||||
title: Troubleshooting React Native Issues
|
||||
sidebar_label: React Native Issues
|
||||
custom_edit_url: https://www.internalfb.com/intern/diffusion/FBS/browsefile/master/xplat/sonar/docs/react-native.mdx
|
||||
---
|
||||
import useBaseUrl from '@docusaurus/useBaseUrl';
|
||||
|
||||
Flipper is a work in progress and issues may occur. This page contains known issues associated with React Native and provides steps you can take to try to resolve them.
|
||||
|
||||
Make sure the project is using the [latest Flipper SDK](getting-started/react-native.mdx#using-the-latest-flipper-sdk).
|
||||
|
||||
When using Flipper with React Native, two devices should show up:
|
||||
|
||||
1. **The 'React Native' device** - this is the "device" that talks to the Metro server and shows plugins that connect to or through Metro, such as the React DevTools, the Hermes Debugger and Metro logs.
|
||||
2. **The device on which your app is running** - This is the device that Flipper connects to ADB / IDB. Flipper primarily support emulators and USB connected devices (examples: `SM760FS`, `Pixel 3`, `android_emulator`, and `iPhone 11`).
|
||||
|
||||
### I don't see the 'React Native' device
|
||||
|
||||
1. Make sure that the Metro server is running.
|
||||
2. Make sure you are on React Native 0.62 or higher.
|
||||
3. Verify that the `@react-native-community/cli` version is `0.47.0` or higher (using `yarn why @react-native-community/cli`).
|
||||
|
||||
### I see my device / emulator, but I can't see the app
|
||||
|
||||
1. Make sure you are running a debug build. Flipper *only* supports debug builds.
|
||||
2. If you are upgraded from RN < 0.62.2, make sure you've updated all the dependencies and build related files according to the upgrade helper. For example: <https://react-native-community.github.io/upgrade-helper/?from=0.61.4&to=0.62.2>
|
||||
3. If you upgraded, make sure you made a clean build: `cd android && ./gradlew clean`, `cd iOS && pod install --repo-update`.
|
||||
4. For iOS, make sure it works on a simulator first.
|
||||
5. (Unconfirmed) check the deployment info target in the XCode project settings. Target should be `iOS 9.0`.
|
||||
|
||||
### I'm seeing "certificate verify failed, type = SSL error" in the logs
|
||||
|
||||
Ensure that your device is set to the correct time and time zone for TLS verification to work.
|
||||
|
||||
### I see my app, but I don't see the external plugins I've installed
|
||||
|
||||
1. Make sure you've installed the desktop part of the plugin (usually through 'Manage plugins' in Flipper). If no plugins show up under 'Manage plugins' > 'Status' make sure you've selected your running device in the Flipper toolbar (and *not* 'React Native').
|
||||
2. Make sure you've installed the app part of the plugin. Typically, the installation instructions of the plugin itself need to be followed here.
|
||||
3. Make sure you've installed the latest version of `react-native-flipper` in your app, and run `pod install` in the `iOS` dir afterwards.
|
||||
4. Make sure you've restarted both Flipper and your app.
|
||||
|
||||
### On iOS it seems that the Flipper dependencies are compiled when making a release build
|
||||
|
||||
That is correct. The dependencies won't be included in the release (when using `react-native-flipper` > 0.45) and can't be excluded from the build process.
|
||||
|
||||
### The React DevTools don't seem to connect
|
||||
|
||||
1. Make sure there are no other instances of the React DevTools are running (such as a stand-alone version). Restart Flipper if needed after closing other tools.
|
||||
2. Make sure you have only one device running to connect to. If there are multiple devices, close them and try again (restart Flipper if needed).
|
||||
3. Make sure there is only one RN app running on the device.
|
||||
|
||||
### Cannot inspect an element in the React DevTools: "Could not inspect element with id ..."
|
||||
|
||||
On selecting a specific element in the React DevTools, the "Could not inspect element with id XXX" appears when the version of the DevTools shipped in Flipper is incompatible with the `react-devtools-core` package used by the React Native application.
|
||||
|
||||
Flipper supports using a globally installed `react-devtools` (after using `npm install -g react-devtools@x.x.x`) instead of the embedded one. This should help with any compatibility issues.
|
||||
|
||||
Another way to fix this is to set the `resolutions` field in the `package.json` of the app to force a specific version and then run `yarn install`, for example:
|
||||
|
||||
```json
|
||||
"resolutions": {
|
||||
"react-devtools-core": "4.13.2"
|
||||
}
|
||||
```
|
||||
|
||||
### How to select a specific element in the React DevTools?
|
||||
|
||||
1. Trigger the debug menu on your RN app (you can use the button in the Flipper toolbar).
|
||||
2. Use `Show Inspector`. Flipper now follows the selection on your device.
|
||||
|
||||
### The Hermes Debugger does not connect
|
||||
|
||||
1. Make sure the Hermes engine is [enabled](https://reactnative.dev/docs/hermes).
|
||||
2. Make sure only one device with React Native is running.
|
||||
3. Make sure there is only one RN app running on the device.
|
||||
4. Make sure the React Native app is *not* in debug mode already (trigger dev menu, and make sure that `Remote JS Debugging` is *not* enabled).
|
||||
|
||||
### iOS Build errors in React Native
|
||||
|
||||
First, make sure your cocoapods is up to date (`sudo gem install cocoapods`), and that you are using the [latest FlipperKit](../react-native.mdx#using-the-latest-flipper-sdk).
|
||||
|
||||
For inexplainable build errors, clone and verify if our [reference project](https://github.com/facebook/flipper/tree/main/react-native/ReactNativeFlipperExample) builds and runs locally. If it does, it's recommended to compare the `package.json` and `ios/Podfile` files with yours. If that doesn't yield anything, compare the `ios/Podfile.lock` as well to verify any transitive pod dependencies need updating.
|
||||
|
||||
### `YogaKit.modulemap` not found
|
||||
|
||||
1. Make sure you are opening the `.xcodeworkspace` dir when building from XCode, *not* the project file. Pods based projects should always be opened this way.
|
||||
2. Make sure you've run `cd ios && pod install`.
|
||||
3. Restarting your machine seems to magically fix the issue for quite some people. This might especially be needed after doing an XCode upgrade.
|
||||
4. Make sure that the simulators are spawned by your current Xcode version. Force quite all simulators, run `sudo xcode-select --switch /Applications/Xcode.app` (update path were necessary) and start simulators & Flipper again.
|
||||
5. Make sure the iOS build target version aligns with the podfile and target iOS 11 (see the following [Example](https://github.com/facebook/react-native/issues/28503#issuecomment-696026013)).
|
||||
6. [Verify](https://github.com/facebook/react-native/issues/28503#issuecomment-621662670) XCode has enough permissions.
|
||||
7. More solutions might be found in this [thread](https://github.com/facebook/react-native/issues/28503).
|
||||
|
||||
### Swift errors
|
||||
|
||||
If you experience errors such as `Undefined symbol: associated type descriptor for FloatLiteralType` or `Undefined symbol: __swift_FORCE_LOAD_$_swiftCompatibility50` after going through the [Getting Started](../index.mdx) page, do the following:
|
||||
|
||||
1. Open your project in Xcode.
|
||||
2. Click in your project's name on the left side.
|
||||
3. Make sure that you choose your project under `PROJECT` on the screen that has been opened.
|
||||
4. Go to the tab `Build Settings`.
|
||||
5. Search for `LD_RUNPATH_SEARCH_PATHS` (make sure that `All` is selected).
|
||||
6. Double-click `Runpath Search Paths` and, in the dialog that opens, click on the plus button at the bottom-left corner and paste `/usr/lib/swift $(inherited)` there.
|
||||
|
||||
<img alt="Screenshot showing the places mentioned in the first steps" src={useBaseUrl("img/troubleshooting-react-native-ios-swift.png")} />
|
||||
|
||||
7. Now search for `LIBRARY_SEARCH_PATHS`.
|
||||
8. Double-click `Library Search Paths` and, in the dialog that opens, add the following items.
|
||||
|
||||
```bash
|
||||
"$(TOOLCHAIN_DIR)/usr/lib/swift/$(PLATFORM_NAME)"
|
||||
"$(TOOLCHAIN_DIR)/usr/lib/swift-5.0/$(PLATFORM_NAME)"
|
||||
"$(inherited)"
|
||||
```
|
||||
|
||||
:::note
|
||||
All of them should be added as `non-recursive` (the default).
|
||||
:::
|
||||
|
||||
In the end it should look as follows:
|
||||
|
||||
<img alt="Screenshot showing the places mentioned in the last steps" src={useBaseUrl("img/troubleshooting-react-native-ios-swift-2.png")} />
|
||||
|
||||
Now you can run your build normally.
|
||||
|
||||
## Opting out from Flipper (iOS)
|
||||
|
||||
Comment out the relevant lines in `ios/Podfile` and run `cd ios && pod install` again:
|
||||
|
||||
```ruby
|
||||
# use_flipper!
|
||||
# post_install do |installer|
|
||||
# flipper_post_install(installer)
|
||||
# end
|
||||
```
|
||||
|
||||
## Disable Flipper on CI builds (iOS)
|
||||
|
||||
To speed up CI builds, Flipper can be disabled on CI environments by making the Flipper SDK inclusion conditional (this works on most CI providers, feel free to customize the environment variable):
|
||||
|
||||
```ruby
|
||||
if !ENV['CI']
|
||||
use_flipper!
|
||||
post_install do |installer|
|
||||
flipper_post_install(installer)
|
||||
end
|
||||
end
|
||||
```
|
||||
14
docs/getting-started/troubleshooting/troubleshooting.mdx
Normal file
14
docs/getting-started/troubleshooting/troubleshooting.mdx
Normal file
@@ -0,0 +1,14 @@
|
||||
---
|
||||
id: troubleshooting
|
||||
title: Troubleshooting Introduction
|
||||
sidebar_label: Introduction
|
||||
custom_edit_url: https://www.internalfb.com/intern/diffusion/FBS/browsefile/master/xplat/sonar/docs/getting-started/troubleshooting/troubleshooting.mdx
|
||||
---
|
||||
|
||||
Flipper is a work in progress and, as such, there's a chance that issues may occur while you're using it.
|
||||
|
||||
The 'troubleshooting' section contains known issues that have occurred within various Flipper environments and the steps you can take if you encounter them.
|
||||
|
||||
If the information in this section doesn't help or if you encounter an issue that is not covered, please post the details in the [Flipper Support](https://fb.facebook.com/groups/230455004101832/) Workplace group first.
|
||||
|
||||
Likewise, if you have a Flipper-related questions, please post it in the [Flipper Support](https://fb.facebook.com/groups/230455004101832/) Workplace group.
|
||||
@@ -1,294 +0,0 @@
|
||||
---
|
||||
id: troubleshooting
|
||||
title: Troubleshooting Issues
|
||||
sidebar_label: Troubleshooting Issues
|
||||
custom_edit_url: https://www.internalfb.com/intern/diffusion/FBS/browsefile/master/xplat/sonar/docs/troubleshooting.mdx
|
||||
---
|
||||
import useBaseUrl from '@docusaurus/useBaseUrl';
|
||||
|
||||
import InternalTroubleshooting from './fb/_internal-troubleshooting.mdx';
|
||||
|
||||
import PortalTroubleshooting from './fb/_portal-troubleshooting.mdx';
|
||||
|
||||
We hope that Flipper works well out of the box, but the software is a work in progress and problems will occur. Below are some known issues and steps you can take to try to resolve them.
|
||||
|
||||
<FbInternalOnly>
|
||||
|
||||
## General Issues
|
||||
|
||||
<InternalTroubleshooting />
|
||||
|
||||
</FbInternalOnly>
|
||||
|
||||
## Mac Desktop app
|
||||
|
||||
### Flipper won't launch on Mac
|
||||
|
||||
* If the window is appearing, try opening the Chrome DevTools within Flipper. To do so, from the View menu select Toggle Developer Tools or press CMD+Option+I and check if there are any errors on the console.
|
||||
* Launch Flipper from the command line using `/Applications/Flipper.app/Contents/MacOS/Flipper`. This should give you some logs, that might be helpful when debugging.
|
||||
* Delete `~/.flipper` and try relaunching Flipper.
|
||||
* Delete Flipper from your applications folder and redownload [Flipper](https://www.facebook.com/fbflipper/public/mac).
|
||||
* If you're using `yarn start` to run from source, make sure all dependencies are installed correctly by running yarn install.
|
||||
|
||||
### Flipper shows weird render artifacts
|
||||
|
||||
This is a long standing MacOS + Electron issue outside our control. In general restarting your computer fixes the problem.
|
||||
For a quick, temporarily work around start Flipper with hardware acceleration disabled. Please note that this will consume a lot of CPU: `FLIPPER_DISABLE_GPU=1 open -a Flipper`.
|
||||
|
||||
### iOS Simulator fails to connect with error "Failed to find device..."
|
||||
|
||||
Try executing `idb kill` and restarting Flipper. See [this comment](https://fb.workplace.com/groups/flippersupport/posts/1288502608297061/?comment_id=1290222721458383&reply_comment_id=1290374518109870) for details.
|
||||
|
||||
### iOS Simulator missing from devices dropdown
|
||||
|
||||
* Check that `xcode-select -p` shows the same XCode version that you're using. If not, see xcode-select for how to select the correct version.
|
||||
|
||||
### iOS physical device not showing up
|
||||
|
||||
Make sure [`idb`](https://fbidb.io/docs/installation) is installed and configured in the Flipper settings.
|
||||
|
||||
### App on physical iOS device stuck in 'connecting...' state
|
||||
|
||||
Make sure you are building and installing the application from source.
|
||||
|
||||
### No plugins showing up for your device
|
||||
|
||||
* Check your device isn't on the list of [known incompatibilities](#known-incompatibilities).
|
||||
* Make sure your version of Flipper is up to date.
|
||||
* Make sure the mobile SDK you are using is relatively recent (<1 month old).
|
||||
* Open Chrome dev tools within Flipper. To do so, from the View menu select Toggle Developer Tools or press CMD+Option+I and check if there are any errors on the console.
|
||||
* Delete `~/.flipper`.
|
||||
* **Uninstall** and reinstall the mobile app.
|
||||
* Make sure the time and date are set correctly on your mobile device and desktop computer.
|
||||
* If no app plugins are showing up, there may be a connectivity issue between Flipper and your app. Check [connection issues](#connection-issues) to see if anything is failing.
|
||||
|
||||
<OssOnly>
|
||||
|
||||
### Connection Issues
|
||||
The Flipper SDK includes an in-app connection diagnostics screen to help you diagnose problems.
|
||||
|
||||
#### Android
|
||||
Replace `<APP_PACKAGE>` below with the package name of your app, e.g. `com.facebook.flipper.sample`.
|
||||
On a terminal, run the following:
|
||||
```bash
|
||||
adb shell am start -n <APP_PACKAGE>/com.facebook.flipper.android.diagnostics.FlipperDiagnosticActivity
|
||||
```
|
||||
This will only work if you added `FlipperDiagnosticActivity` to your `AndroidManifest.xml`. See [getting started](./getting-started/android-native.mdx#diagnostics) for help.
|
||||
|
||||
#### iOS
|
||||
You'll need to manually add this [ViewController](https://github.com/facebook/flipper/blob/main/iOS/FlipperKit/FlipperDiagnosticsViewController.m) to your app to see the in-app diagnostics.
|
||||
|
||||
</OssOnly>
|
||||
|
||||
### Known Incompatibilities
|
||||
|
||||
The following devices are known to be incompatible or face issues with Flipper:
|
||||
|
||||
* Some Samsung devices ([Tracking Issue](https://github.com/facebook/flipper/issues/92)).
|
||||
* Genymotion emulators on Android 8+ are reported to have issues.
|
||||
|
||||
### File an Issue
|
||||
Still not working? File an issue on [GitHub](https://github.com/facebook/flipper/issues) with the chrome DevTools logs and the output from the diagnostics screen, if relevant.
|
||||
|
||||
## Android
|
||||
|
||||
### Exception from call site #4 bootstrap method
|
||||
|
||||
Build error after including the Flipper dependency:
|
||||
|
||||
```
|
||||
Exception from call site #4 bootstrap method
|
||||
```
|
||||
|
||||
This can happen because we include [OkHttp3](https://github.com/square/okhttp/issues/4597#issuecomment-461204144) as dependency which makes use of Java 8 features. There are two ways of dealing with this:
|
||||
|
||||
**Enable Java 8 support**
|
||||
|
||||
Add this to your Gradle config:
|
||||
|
||||
```groovy
|
||||
android {
|
||||
compileOptions {
|
||||
targetCompatibility = "8"
|
||||
sourceCompatibility = "8"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Exclude the OkHttp3 dependency**
|
||||
|
||||
Alternatively, if you don't plan on making use of OkHttp, you can exclude the dependency from the build entirely:
|
||||
|
||||
```
|
||||
debugImplementation('com.facebook.flipper:flipper:*') {
|
||||
exclude group: 'com.squareup.okhttp3'
|
||||
}
|
||||
```
|
||||
|
||||
### Duplicate class `com.facebook.jni.*`
|
||||
|
||||
This can occur when mixing different versions of [FBJNI](https://github.com/facebookincubator/fbjni),
|
||||
a library we use to interact with native C++ code.
|
||||
|
||||
Speficially, this can happen when the versions `0.0.x` and `0.1.x` are mixed. Version `0.1.0` of FBJNI
|
||||
switched to using [Google Prefab](https://google.github.io/prefab/) for distributing native artifacts,
|
||||
which made the split into combined, "java-only" and "header" packages redundant and only requires
|
||||
a single dependency in your projects.
|
||||
|
||||
When including both "fbjni-java-only:0.0.1" and "fbjni:0.1.0" in one project, you will now
|
||||
duplicate class errors during the build process. You must ensure that only one of the two
|
||||
versions is used in your entire dependency tree. Start by looking at `./gradlew :myapp:dependencies`
|
||||
to see where the different version requirements come from. Then exclude the FBJNI dependency from
|
||||
one of them, e.g.
|
||||
|
||||
```groovy
|
||||
implementation("com.facebook.react:react-native:+") {
|
||||
exclude group:'com.facebook.fbjni'
|
||||
}
|
||||
```
|
||||
|
||||
## React Native
|
||||
|
||||
Make sure the project is using the [latest Flipper SDK](getting-started/react-native.mdx#using-the-latest-flipper-sdk).
|
||||
|
||||
When using Flipper with React Native, two devices should show up:
|
||||
|
||||
1. The 'React Native' device. This is the "device" that talks to the Metro server and shows plugins that connect to or through Metro, such as the React DevTools, the Hermes Debugger and Metro logs.
|
||||
1. The device on which your app is running (like `SM760FS`, `Pixel 3`, `android_emulator`, `iPhone 11`). This is the device that Flipper connects to ADB / IDB. We primarily support emulators and USB connected devices.
|
||||
|
||||
#### Q: I don't see the 'React Native' device
|
||||
|
||||
1. Make sure that the Metro server is running.
|
||||
1. Make sure you are on React Native 0.62 or higher.
|
||||
1. Verify that the `@react-native-community/cli` version is `0.47.0` or higher (using `yarn why @react-native-community/cli`).
|
||||
|
||||
#### Q: I see my device / emulator, but I can't see the app
|
||||
|
||||
1. Make sure you are running a debug build. Flipper _only_ supports debug builds.
|
||||
1. If you are upgraded from RN < 0.62.2, make sure you've updated all the dependencies and build related files according to the upgrade helper. For example: https://react-native-community.github.io/upgrade-helper/?from=0.61.4&to=0.62.2
|
||||
1. If you upgraded, make sure you made a clean build: `cd android && ./gradlew clean`, `cd iOS && pod install --repo-update`.
|
||||
1. For iOS, make sure it works on a simulator first.
|
||||
1. (Unconfirmed) check the deployment info target in the XCode project settings. Target should be `iOS 9.0`.
|
||||
|
||||
#### Q: I'm seeing "certificate verify failed, type = SSL error" in the logs
|
||||
|
||||
Ensure that your device is set to the correct time and timezone for TLS verification to work.
|
||||
|
||||
#### Q: I see my app, but I don't see the external plugins I've installed
|
||||
|
||||
1. Make sure you've installed the desktop part of the plugin (usually through "Manage plugins" in Flipper). If no plugins show up under "Manage plugins" > "Status", make sure you've selected your running device in the Flipper toolbar (and _not_ "React Native").
|
||||
1. Make sure you've installed the app part of the plugin. Typically the installation instructions of the plugin itself need to be followed here.
|
||||
1. Make sure you've installed the latest version of `react-native-flipper` in your app, and run `pod install` in the `iOS` dir afterwards.
|
||||
1. Make sure you've restarted both Flipper and your app.
|
||||
|
||||
#### Q: On iOS it seems that the Flipper dependencies are compiled when making a release build
|
||||
|
||||
That is correct, the dependencies won't be actually included in the release (when using `react-native-flipper` > 0.45), but sadly we can't exclude those dependencies from the build process.
|
||||
|
||||
#### Q: The React DevTools don't seem to connect
|
||||
|
||||
1. Make sure there are no other instances of the React DevTools are running (For example a stand-alone version). Restart Flipper if needed after closing other tools.
|
||||
1. Make sure you have only one device running to connect to. If there are multiple devices, close them and try again (restart Flipper if needed).
|
||||
1. Make sure there is only one RN app running on the device
|
||||
|
||||
#### Q: Cannot inspect an element in the React DevTools: "Could not inspect element with id ..."
|
||||
|
||||
The "Could not inspect element with id XXX" error will appear when selecting a specific element in the React DevTools, when the version of the DevTools shipped in Flipper is incompatible with the `react-devtools-core` package used by the React Native application.
|
||||
|
||||
Flipper supports using a globally installed `react-devtools` (after using `npm install -g react-devtools@x.x.x`) instead of the embedded one.
|
||||
This should help with any compatibility issues.
|
||||
|
||||
Another way to fix this is to set the `resolutions` field in the `package.json` of the app to force a specific version and then run `yarn install`, for example:
|
||||
|
||||
```json
|
||||
"resolutions": {
|
||||
"react-devtools-core": "4.13.2"
|
||||
}
|
||||
```
|
||||
|
||||
#### Q: How to select a specific element in the React DevTools?
|
||||
|
||||
1. Trigger the debug menu on your RN app (you can use the button in the Flipper toolbar for that)
|
||||
1. Use `Show Inspector`. Flipper will now follow the selection on your device.
|
||||
|
||||
#### Q: The Hermes Debugger does not connect
|
||||
|
||||
1. Make sure the Hermes engine is [enabled](https://reactnative.dev/docs/hermes)
|
||||
1. Make sure only one device with React Native is running
|
||||
1. Make sure there is only one RN app running on the device
|
||||
1. Make sure the React Native app is _not_ in debug mode already (trigger dev menu, and make sure that `Remote JS Debugging` is _not_ enabled).
|
||||
|
||||
#### iOS Build errors in React Native
|
||||
|
||||
First, make sure your cocoapods is up to date (`sudo gem install cocoapods`), and that you are using the [latest FlipperKit](getting-started/react-native.mdx#using-the-latest-flipper-sdk).
|
||||
|
||||
For inexplainable build errors, clone and verify if our [reference project](https://github.com/facebook/flipper/tree/main/react-native/ReactNativeFlipperExample) builds and runs locally. If it does, we recommend to compare the `package.json` and `ios/Podfile` files with yours. If that doesn't yield anything, compare the `ios/Podfile.lock` as well to verify any transitive pod dependencies need updating.
|
||||
|
||||
#### `YogaKit.modulemap` not found
|
||||
|
||||
1. Make sure you are opening the `.xcodeworkspace` dir when building from XCode, _not_ the project file. Pods based projects should always be opened this way.
|
||||
1. Make sure you did run `cd ios && pod install`.
|
||||
1. Restarting your machine seems to magically fix the issue for quite some people. This might especially be needed after doing an XCode upgrade.
|
||||
1. Make sure that the simulators are spawned by your current Xcode version. Force quite all simulators, run `sudo xcode-select --switch /Applications/Xcode.app` (update path were necessary), and start simulators & Flipper again.
|
||||
1. Make sure the iOS build target version aligns with the podfile and target iOS 11. [Example](https://github.com/facebook/react-native/issues/28503#issuecomment-696026013)
|
||||
1. [Verify](https://github.com/facebook/react-native/issues/28503#issuecomment-621662670) XCode has enough permissions.
|
||||
1. More solutions might be found in this [thread](https://github.com/facebook/react-native/issues/28503).
|
||||
|
||||
#### Swift errors
|
||||
|
||||
If you experience errors such as `Undefined symbol: associated type descriptor for FloatLiteralType` or `Undefined symbol: __swift_FORCE_LOAD_$_swiftCompatibility50` after going through the [Getting Started](getting-started/index.mdx) tutorial you must do as follows:
|
||||
|
||||
1. Open your project in Xcode;
|
||||
1. Click in your project's name on the left side;
|
||||
1. Make sure that you choose your project under `PROJECT` on the screen that has been opened;
|
||||
1. Go to the tab `Build Settings`;
|
||||
1. Search for `LD_RUNPATH_SEARCH_PATHS` (make sure that `All` is selected);
|
||||
1. Double-click `Runpath Search Paths` and, in the dialog that opens, click on the plus button at the bottom-left corner and paste `/usr/lib/swift $(inherited)` there;
|
||||
<img alt="Screenshot showing the places mentioned in the first steps" src={useBaseUrl("img/troubleshooting-react-native-ios-swift.png")} />
|
||||
1. Now search for `LIBRARY_SEARCH_PATHS`;
|
||||
1. Double-click `Library Search Paths` and, in the dialog that opens, add the following items:
|
||||
|
||||
```
|
||||
"$(TOOLCHAIN_DIR)/usr/lib/swift/$(PLATFORM_NAME)"
|
||||
"$(TOOLCHAIN_DIR)/usr/lib/swift-5.0/$(PLATFORM_NAME)"
|
||||
"$(inherited)"
|
||||
```
|
||||
|
||||
_Note: all of them should be added as `non-recursive` (the default)._
|
||||
|
||||
In the end it should look like this:
|
||||
<img alt="Screenshot showing the places mentioned in the last steps" src={useBaseUrl("img/troubleshooting-react-native-ios-swift-2.png")} />
|
||||
|
||||
1. Now you can run your build normally.
|
||||
|
||||
#### Opting out from Flipper (iOS)
|
||||
|
||||
Comment out the relevant lines in `ios/Podfile` and run `cd ios && pod install` again:
|
||||
|
||||
```ruby
|
||||
# use_flipper!
|
||||
# post_install do |installer|
|
||||
# flipper_post_install(installer)
|
||||
# end
|
||||
```
|
||||
|
||||
#### Disable Flipper on CI builds (iOS)
|
||||
|
||||
To speed up CI builds, Flipper can be disabled on CI environments by making the Flipper SDK inclusion conditional (this works on most CI providers, feel free to customize the environment variable):
|
||||
|
||||
```ruby
|
||||
if !ENV['CI']
|
||||
use_flipper!
|
||||
post_install do |installer|
|
||||
flipper_post_install(installer)
|
||||
end
|
||||
end
|
||||
```
|
||||
|
||||
<FbInternalOnly>
|
||||
|
||||
## Portal
|
||||
|
||||
<PortalTroubleshooting />
|
||||
|
||||
</FbInternalOnly>
|
||||
@@ -219,7 +219,7 @@ const siteConfig = {
|
||||
{
|
||||
redirects: [
|
||||
{
|
||||
to: '/docs/troubleshooting',
|
||||
to: '/docs/getting-started/troubleshooting/troubleshooting',
|
||||
from: ['/docs/fb/troubleshooting'],
|
||||
},
|
||||
{
|
||||
|
||||
@@ -59,7 +59,16 @@ module.exports = {
|
||||
},
|
||||
...fbInternalOnly(['getting-started/fb/connecting-to-flipper']),
|
||||
...fbInternalOnly(['getting-started/fb/flipper-on-demand']),
|
||||
'troubleshooting',
|
||||
{
|
||||
'Troubleshooting': [
|
||||
'getting-started/troubleshooting/troubleshooting',
|
||||
...fbInternalOnly(['getting-started/troubleshooting/general-issues']),
|
||||
'getting-started/troubleshooting/mac-desktop-app',
|
||||
'getting-started/troubleshooting/android',
|
||||
'getting-started/troubleshooting/react-native',
|
||||
...fbInternalOnly(['getting-started/troubleshooting/portal']),
|
||||
],
|
||||
},
|
||||
{
|
||||
'Other Platforms': [
|
||||
'extending/new-clients',
|
||||
|
||||
Reference in New Issue
Block a user