Skip to content

Troubleshooting

This article provides basic troubleshooting steps for HarmonyOS SDK initialization and reporting exceptions.

Initialization Failure

If SDK initialization fails, it is recommended to first check:

  1. Whether datakitUrl, datawayUrl, and clientToken are correctly configured according to the deployment method.
  2. Whether ft_sdk.har and ft_native.har have been correctly placed in the libs directory, and declared in oh-package.json5 as @guancecloud/ft_sdk and @guancecloud/ft_native respectively, followed by executing ohpm install.
  3. Whether the application has completed the dependency declaration in oh-package.json5 as per the documentation.
  4. Whether SDK initialization occurs during the application startup phase.

No Data Reporting

It is recommended to troubleshoot in the following order:

  1. Confirm that the prerequisites have been completed, especially the DataKit and RUM collector configurations.
  2. Confirm that the application device can access datakitUrl or datawayUrl.
  3. Enable setDebug(true) and check the initialization and reporting logs.
  4. Confirm that RUM has executed installRUMConfig and at least one collection item requiring verification is enabled.

HttpInterceptorChain Not Working

If the automatic collection using @kit.NetworkKit's HttpInterceptorChain does not take effect, it is recommended to first check:

  1. Whether the current device or compilation target is HarmonyOS API 22 or higher; this capability is not supported below API 22.
  2. Whether ft_sdk.har and ft_sdk_ext.har have been installed in the project, and declared in oh-package.json5 as @guancecloud/ft_sdk and @guancecloud/ft_sdk_ext respectively, followed by completing ohpm install.
  3. Whether setEnableTraceUserResource(true) has been enabled; if automatic injection of Trace Headers is needed, also enable setEnableAutoTrace(true) in the Trace configuration.
  4. It is known that in concurrent request scenarios using @kit.NetworkKit, even if independent HttpRequest and HttpInterceptorChain are created for each request, an exception may still be triggered: {"code":2300003,"message":"Invalid URL format or missing URL"}.
  5. If encountering the above error, it is recommended to first downgrade to serial verification for validation; in concurrent scenarios, consider switching to RCP or Axios compatibility mode, or temporarily avoid using HttpInterceptorChain in high-concurrency links.

Resource Not Collected

If an HTTP request has been created and the automatic collection interceptor is mounted, but the SDK initialization and RUM configuration are executed later, it is possible that the request succeeds but Resource data is not generated.

It is recommended to first check:

  1. Whether HttpRequest was created first, createFTHttpInterceptorChain() or applyFTHttpTrack() was called, and then FTSDK.installRUMConfig() was executed later.
  2. Whether setEnableTraceUserResource(true) has been enabled in the RUM configuration.

Reason explanation:

  • When HttpInterceptorChain is created, it immediately reads the current RUM configuration to decide whether to enable automatic Resource collection.
  • If this step occurs before FTSDK.installRUMConfig(), the default value read by the SDK is false.
  • Subsequently, even if SDK initialization is completed later, the already created automatic collection interceptor instance will not automatically refresh to the enabled state, and therefore will not generate Resource.

Recommended handling methods:

  1. Complete FTSDK.install() and FTSDK.installRUMConfig() first, then create HttpRequest and mount HttpInterceptorChain.
  2. If the request object or interceptor chain has been created in advance, it needs to be recreated and remounted after SDK initialization is completed.
  3. If it is indeed necessary to create the automatic collection object before SDK initialization, you can explicitly pass the switch when creating it to avoid relying on the default configuration value.

Optional writing example:

applyFTAxiosTrack(client, {
  enableTraceInterceptor: true,
  enableResourceInterceptor: true
});

sdk.init();

Note:

  • Explicitly passing enableTraceInterceptor and enableResourceInterceptor can only ensure that the automatic collection mechanism itself is in an enabled state.
  • Requests already sent before SDK initialization is completed may still fail to generate or complete Resource data because the RUM context has not been initialized yet.
  • Therefore, the more recommended approach is still to complete SDK initialization first, then create and use the automatic collection object.

Similar handling methods also apply to RCP and HttpInterceptorChain:

  • Axios: applyFTAxiosTrack(client, { enableTraceInterceptor: true, enableResourceInterceptor: true })
  • RCP: createFTRCPInterceptors(true, true) or createFTRCPTrackConfig({ enableTraceInterceptor: true, enableResourceInterceptor: true })
  • HTTP: createFTHttpInterceptorChain({ enableTraceInterceptor: true, enableResourceInterceptor: true }) or applyFTHttpTrack(request, { enableTraceInterceptor: true, enableResourceInterceptor: true })

Cache and Synchronization

  • If automatic synchronization is turned off, i.e., autoSync = false, you need to manually call FTSDK.flushSyncData() mentioned in SDK Initialization.
  • If local cache is abnormal, you can use FTSDK.clearAllData() to clean up unreported data and then re-verify.

Feedback

Is this page helpful? ×