What happens
When the installed HarmonyOS SDK is too old for a dependency, the build fails deep inside ArkTS compilation with errors that never mention the SDK:
1 ERROR: 10505001 ArkTS Compiler Error
Error Message: Property 'isCapsLockOn' does not exist on type 'KeyEvent'.
At File: .../oh_modules/.ohpm/@ohos+flutter_ohos@.../embedding/ohos/KeyEventHandler.ets:121:34
...
Error Message: Property 'getGlobalWindowMode' does not exist on type 'typeof window'.
At File: .../embedding/ohos/PiPVisibilityBridge.ets:119:33
COMPILE RESULT:FAIL {ERROR:7 WARN:977}
Seven errors, all pointing into a dependency's internals, all one root cause: the SDK was HarmonyOS 5.1.0 / API 18, while @ohos/flutter_ohos calls KeyEvent.isCapsLockOn (@since 19) and window.getGlobalWindowMode (@since 20).
Diagnosing this took cross-referencing @since annotations between two SDK trees. Nothing in the output names the SDK in use or its API level.
Proposed change
On a failed HarmonyOS build, append a footer naming the SDK actually used:
Built against HarmonyOS 5.1.0 (API 18) at /home/user/command-line-tools/sdk.
If errors name missing properties or APIs, a dependency may require a newer API level.
Everything needed is already in hand — requireHarmonyOsSdk() returns displayName, version and sdkPath, and runHvigorw holds that object. It is a message-only change on the failure path.
A limit worth stating
A metadata-based preflight would not have caught this case, so it is not worth over-investing in dependency scanning: the HAR advertises "compatibleSdkType": "HarmonyOS", "compatibleSdkVersion": 12 while in fact requiring API 20. Its own declared floor is wrong by eight levels. The cheap footer is the realistic fix.
Related: packages/core/src/project/create.ts already does the analogous check at scaffold time ("The HarmonyOS SDK at X is , so a project declaring will not build against it"), which is a good precedent for the wording.
Environment
oniro-app 0.11.0 · failing SDK: HarmonyOS 5.1.0 / API 18 (commandline-tools-linux-x64-5.1.0.840.zip, the newest on the public Huawei mirror) · fixed by HarmonyOS 6.1.1 / API 24
What happens
When the installed HarmonyOS SDK is too old for a dependency, the build fails deep inside ArkTS compilation with errors that never mention the SDK:
Seven errors, all pointing into a dependency's internals, all one root cause: the SDK was HarmonyOS 5.1.0 / API 18, while
@ohos/flutter_ohoscallsKeyEvent.isCapsLockOn(@since 19) andwindow.getGlobalWindowMode(@since 20).Diagnosing this took cross-referencing
@sinceannotations between two SDK trees. Nothing in the output names the SDK in use or its API level.Proposed change
On a failed HarmonyOS build, append a footer naming the SDK actually used:
Everything needed is already in hand —
requireHarmonyOsSdk()returnsdisplayName,versionandsdkPath, andrunHvigorwholds that object. It is a message-only change on the failure path.A limit worth stating
A metadata-based preflight would not have caught this case, so it is not worth over-investing in dependency scanning: the HAR advertises
"compatibleSdkType": "HarmonyOS", "compatibleSdkVersion": 12while in fact requiring API 20. Its own declared floor is wrong by eight levels. The cheap footer is the realistic fix.Related:
packages/core/src/project/create.tsalready does the analogous check at scaffold time ("The HarmonyOS SDK at X is , so a project declaring will not build against it"), which is a good precedent for the wording.Environment
oniro-app 0.11.0 · failing SDK: HarmonyOS 5.1.0 / API 18 (
commandline-tools-linux-x64-5.1.0.840.zip, the newest on the public Huawei mirror) · fixed by HarmonyOS 6.1.1 / API 24