Skip to content

Troubleshooting

SDK Initialization Error Checks

Check Logcat to see whether there are any logs whose Level is Error and whose Tag is prefixed with [FT-SDK]

14:46:04.825 [FT-SDK] com.demo E 请先安装SDK(在应用启动时调用FTSdk.install(FTSDKConfig ftSdkConfig))

In a Debug environment, after you configure the Guance SDK and run the application for the first time, check your debugger console in Xcode. The SDK uses assertions to check the correctness of multiple configurations, and it crashes with relevant warnings when a configuration is incorrect.

eg: If the datakit metrics write address is not set when configuring the SDK, the application crashes and outputs a warning ⚠️ in the console.

*** Assertion failure in +[FTMobileAgent startWithConfigOptions:], FTMobileAgent.m:53
*** Terminating app due to uncaught exception 'NSInternalInconsistencyException', reason: '请设置 datakit metrics 写入地址'

Enable Debug Mode

You can enable the SDK debug feature with the following configuration.

 let config: FTMobileConfig = {
    serverUrl: Config.SERVER_URL,
    debug: true
 };
 FTMobileReactNative.sdkConfig(config);

We recommend disabling this setting when releasing a Release build

Check the logs whose Tag is prefixed with [FT-SDK] in Logcat

SDK debug logs are prefixed with [FTLog].

  • When you run the app with Xcode, you can view the SDK debug logs directly in the Xcode debug console.

  • When you run yarn ios or yarn react-native run-ios from a terminal, you can view the SDK debug logs in "Console" on your Mac.

Using "Console":

Select Action and check Include Info Messages and Include Debug Messages.

Select the device to debug, click the Start button, and enter the search condition [FTLog] in the search box on the right. You can then view the SDK debug logs.

console_app_use

Log examples for Android Logcat and iOS Xcode Console

SDK Runs Normally but No Data Is Reported

  • Check whether DataKit is running normally

  • Verify that the SDK upload address datakitUrl or datawayUrl is configured correctly and that the SDK is initialized correctly. In debug mode, check the sync logs of Android Logcat or iOS Xcode Console.

  • Check whether DataKit uploads data to the corresponding workspace and whether it is offline. You can confirm this by logging in to Guance and viewing "Infrastructure".

Data Loss

Partial Data Loss

  • If some RUM Session data, or a few Log or Trace records, are missing, first rule out whether a sampling rate below 100 was set in FTRUMConfig, FTLogConfig, or FTTraceConfig (sessionSamplingRate, logSamplingRate, traceSamplingRate), or whether sampleRate < 1 was used without configuring the new fields. Starting from SDK 0.4.3, when both the old and new fields are set, the new fields take precedence. For details, see Sampling Configuration.

  • Is the collected RUM data incomplete, with no Resource or Action data?

    Resource and Action data are bound to a View. Make sure that the FTReactNativeRUM.startView operation is performed. You can refer to the RUM View documentation to implement View event collection.

  • Check the network of the device that uploads data, as well as the network and load of the device where DataKit is installed.

Compatibility Issues

react-native-navigation Runtime Compatibility Issues

Cannot Find Symbol ReactTextShadowNode.UNSET

This is caused by a version compatibility issue in react-native-navigation. See the related issue here. Fix the issue by modifying or downloading and replacing ReactTypefaceUtils.java.

Cannot Find Module react/jsx-runtime

Affected scope: SDK version 0.3.0 && React version < 16.14.0

Cause: The react/jsx-runtime used internally by the SDK is supported only in React >= 16.14.0.

Recommended fix:

  • Upgrade the SDK to version >= 0.3.1

Note: Adding the @cloudcare/react-native-mobile dependency library via a local path is not recommended, as it may cause errors that cannot be fixed.

Native and React Native Hybrid Development

Error: Cannot read properties of undefined (reading 'addError')

Cause: The RN SDK version is incompatible with the Native SDK version, or the installation is incomplete.

How to verify the issue:

In the root directory of the Android project, run the command ./gradlew app:dependencies in a terminal, and check whether the output contains cloudcare_react-native-mobile.

cloudcare_react-native-mobile is the dependency library installed on the Android side after the RN project adds the Guance RN SDK dependency.

Check the Podfile.lock file to confirm whether the FTMobileReactNativeSDK dependency exists.

FTMobileReactNativeSDK is the dependency library installed on the iOS side after the RN project integrates the Guance RN SDK.

Recommended fix:

  1. Check version compatibility

    • Make sure the RN SDK version matches the native SDK version
    • Paths to the native SDK version information corresponding to the RN SDK:

    node_modules/@cloudcare/react-native-mobile/android/build.gradle

    node_modules/@cloudcare/react-native-mobile/FTMobileReactNativeSDK.podspec

  2. Reinstall dependencies

    • Clean the project cache:
    # Clear the npm cache
    npm cache clean --force
    # Or clear the yarn cache
    yarn cache clean
    
    • Reinstall dependencies:
    # Using npm
    npm install
    # Or using yarn
    yarn install
    # For iOS projects, run in the ios directory
    pod install
    

The steps above can effectively resolve this error caused by version incompatibility or an incomplete installation.

Feedback

Is this page helpful?