HarmonyOS Compilation Troubleshooting: Log Levels, Error Codes & Debug Workflow for ArkTS

Log Levels: Your First Line of Defense

Hvigor defines four log levels that control build output verbosity. Proper use dramatically improves debugging efficiency:

ERROR : Error information, must be addressed.

WARN : Warning information, may affect functionality.

INFO : Normal information, helps understand the build process.

DEBUG : Debug information, most detailed logs.

Log level can be set via hvigor-config.json5 by configuring debugging.logging for level and debugging.stacktrace for stack trace toggle.

Error Codes: Precise Navigation

When compilation fails, the console outputs specific error codes (format ERROR: XXXXXXXX). The official HarmonyOS documentation contains a dedicated Compilation Build Error Codes chapter (located under Guide → Compilation Build Error Codes, alongside "Using Log Recording" and "Compilation Build Common Issues"). This chapter acts as an "ID card" for each error, providing meaning, cause, and solution.

Three-step usage:

Identify & copy the full error code from IDE console or build log.

Search documentation using "Compilation Build Error Codes" plus the specific code.

Apply documented steps for troubleshooting and fix.

Reference: Huawei Developer Documentation Center (https://developer.huawei.com/consumer/cn/doc/)

Common Compilation Errors Quick Reference

(1) Syntax Standard Issues

Symptom : ERROR: 10505001 ArkTS Compiler Error Solution : Usually caused by code violating language specifications. Locate the reported line and correct syntax.

(2) File Import Issues

Symptom : ERROR: 10311001 ArkTS: ERROR Solution : .ts or .js files are not allowed to import .ets files.

(3) Memory Allocation Failure

Symptom :

OpenJDK 64-Bit Server VM warning: INFO: os::commit_memory(...) failed; error='页面文件太小,无法完成操作'

Cause : OS denied memory request, typically due to insufficient virtual memory.

Solution : Increase system virtual memory or optimize project configuration.

Advanced Troubleshooting Techniques

(1) Enable Verbose Debug Mode

Configure hvigor-config.json5:

{
  "logging": {
    "level": "debug"
  },
  "debugging": {
    "stacktrace": true
  }
}

This reveals exact error locations when builds fail.

(2) Clean Cache and Rebuild

When encountering inexplicable errors, stale caches may be the culprit. Steps:

Build → Clean Project.

Manually delete oh_modules folder.

Run ohpm install.

Rebuild project.

(3) Dependency Package Version Check

Release build failures may stem from inconsistent vendor fields. Investigation steps:

File → Settings → Build,Execution,Deployment → Build Tools → Hvigor: set Use log level to Debug.

Re-run Build apps.

In Build log, search for app_packing_tool input parameters to list all dependent HSPs and HAPs.

Ensure vendor values are consistent across all HSPs and HAPs.

One-Step Troubleshooting Workflow (Error Code + Log Combo)

Check error code, determine direction : Focus on console error code to quickly categorize issue (dependency, config, syntax, environment).

Consult documentation, find solution : Use error code to locate authoritative explanation and step-by-step fix in official "Compilation Build Error Codes" chapter.

Enable logs, examine details : If error code guidance is insufficient, use --stacktrace or set log level to debug to obtain detailed call stacks and context, pinpointing exact file and line.

Verify versions, clear cache : Check tool, SDK, and dependency package version consistency; clean build caches to resolve environment or cache-induced "mystical" issues.

Summary

Compilation issue diagnosis is not guesswork but a repeatable technical process. Master log analysis for macro visibility, leverage error codes for precise navigation, and combine with systematic troubleshooting flow to confidently resolve build problems quickly.

Tip : The official "Compilation Build Error Codes" chapter is your primary reference. For uncovered error codes, seek help via Huawei Developer Community Q&A channel or HarmonyOS ArkTS technical exchange groups.