Skip to content

Troubleshooting

This document provides basic troubleshooting entry points 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, declared as @guancecloud/ft_sdk and @guancecloud/ft_native respectively in oh-package.json5, and ohpm install has been executed.
  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 that needs verification is enabled.

HttpInterceptorChain Not Effective

If automatic collection using @kit.NetworkKit's HttpInterceptorChain is not effective, 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, declared as @guancecloud/ft_sdk and @guancecloud/ft_sdk_ext in oh-package.json5, and ohpm install has been completed.
  3. Whether setEnableTraceUserResource(true) has been enabled; if automatic injection of Trace Headers is required, 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 chains.

Resource Not Collected

If an HTTP request has been created and an automatic collection interceptor has been mounted, but 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 after SDK initialization is completed, the already created automatic collection interceptor instance will not automatically refresh to an 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 complete.
  3. If it is indeed necessary to create automatic collection objects before SDK initialization, explicitly pass the switch during creation to avoid relying on default configuration values.

Optional Writing Example:

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

sdk.init();

Note:

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

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 })

Caching and Synchronization

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