目录

restool

Overview

restool is an application resource compilation tool. It parses application resource files to generate files such as resource index files and resource binary files. The generated artifacts are packed into the application package by the packing tool. During application runtime, developers can use the resource management APIs to obtain resources from the application package.

restool is stored in the toolchains folder under the SDK installation directory.

Description

[h2]Command Options

Option Default Value Allowed Argument Carried Description
-i/--inputPath No Yes

Resource directory or resource middleware to create.

You can specify a compiled HAP/HSP resource directory (in the decompressed state) in the resource directory and implement overlay compilation based on the HAP/HSP resource directory.

For details, see Compiling Resources.
-j/--json No Yes Path of the config.json or module.json file.
-o/--outputPath No Yes Output path of the compiled resource.
-p/--packageName No Yes Bundle name of the compiled resource.
-r/--resHeader No Yes

Output path of the header file of the resource. The file contains the mapping between resource names and resource IDs. The file can be in .txt, .js, .h, or .ts format.

NOTE

- The .txt, .js, and .h files contain the resource mapping tables in all resource directories specified by -i.

- Since API version 23, the .ts format is supported. The file contains only the resource mapping table in the resource directory of the HAR build product specified by -i.
-e/--startId Yes Yes Start ID of the generated resource, for example, 0x01000000. The value range is [0x01000000, 0x06FFFFFF) or [0x08000000, 0xFFFFFFFF).
-f/--forceWrite Yes No If the output path already exists, it will be forcibly deleted and regenerated.
-h/--help Yes No Help information.
-m/--modules Yes Yes Module name. During joint module compilation, multiple module names can be specified, separated by commas (,).
-x/--append Yes Yes Resource directory for generating intermediate files or a single resource path. The same command can run multiple times.
-z/--combine Yes No Compilation result generated based on the resource intermediate file directory.
-l/--fileList Yes Yes JSON file of the command option set, for example, resConfig.json. For details, see -l/--fileList Parameters.
-v/--version Yes No Tool version.
--ids Yes Yes Output directory of the generated id_defined.json file.
--defined-ids Yes Yes

Path of the id_defined.json file. Generally, the file is generated by using --ids.

id_defined.json contains a list of resource types, names, and IDs.

You can customize resource IDs in id_defined.json.
--dependEntry Yes Yes Directory of the compilation result of a specified entry module when features are compiled separately in the FA model.
--icon-check Yes No Whether to enable PNG image verification for icons and startWindowIcons.
--compressed-config Yes Yes JSON configuration file for texture compression. For example, opt-compression.json. For details about the JSON configuration file format, see --compressed-config Parameters.
--thread Yes Yes

Number of child threads enabled during resource compilation.

NOTE

This option is supported since API version 18.
--target-config Yes Yes

Used together with the -i command to support compilation selection.

For details, see target-config Parameters.
--ignored-file Yes Yes

Ignoring rule for resource files and resource directories. The value is a regular expression. Multiple rules are separated by colons. Files and directories whose names match the regular expression are ignored.

For example, \.git:\.svn can ignore all files and directories whose names contain .git and .svn.

NOTE

This option is supported since API version 19.
--ignored-path Yes Yes

Ignoring rule for resource files and resource directories. The value is a regular expression. Multiple rules are separated by colons. Files and directories whose names or paths match the regular expression are ignored.

For example, .+/rawfile/\.git:\.svn ignores only .git files and directories in the rawfile directory because it contains the specified path .+/rawfile/. However, all .svn files and directories can be ignored when the regular expression contains no specified path.

NOTE

This option is supported since API version 23.

target-config Parameters

Supported parameters: MccMnc, Locale, Orientation, Device, ColorMode, and Density.

Format: Use semicolons to separate different parameter configurations. Use square brackets ([]) to encapsulate values for a parameter and use commas (,) to separate values.

MccMnc matching rule: The MCC must always be used for matching. If an MNC is not included, a match is found as long as the MCC is the same. If an MNC is included, a match is found when both the MCC and MNC are the same.

Locale matching rules:

  1. The languages must be the same.

  2. If the script (text) does not exist, it is matched by default. Otherwise, it must be the same.

  3. If the country or region does not exist, the country or region is matched by default. Otherwise, the country or region must be the same.

Example: Locale[zh_CN,en_US];Device[phone]. This configuration uses the languages zh_CN and en_US and the device phone as filter criteria. A match is found only when the resources use zh_CN and en_US as the languages and apply to phones. Other parameters (such as MccMnc and Orientation) are not configured and any values of them can match.

-l/--fileList Parameters

These parameters are used to specify the JSON file of the command option set. The following table lists the mapping between the fields in the JSON file and the command options.

Field Type Command Option Description
configPath string -j/--json For details, see the -j/--json description.
packageName string -p/--packageName For details, see the -p/--packageName description.
output string -o/--outputPath For details, see the -o/--outputPath description.
startId string -e/--startId For details, see the -e/--startId description.
moduleNames string -m/--modules For details, see the -o/--outputPath description.
ResourceTable string[] -r/--resHeader You can specify multiple paths, which is equivalent to specifying -r/--resHeader for multiple times.
applicationResource string -i/--inputPath Resource directory of AppScope.
moduleResources string[] -i/--inputPath Resource directory of the current module. You can specify multiple directories, which is equivalent to specifying**-i/--inputPath** for multiple times.
dependencies string[] -i/--inputPath Resource directory of the dependent module. You can specify multiple directories, which is equivalent to specifying**-i/--inputPath** for multiple times.
entryCompiledResource string --dependEntry For details, see the description of --dependEntry.
iconCheck boolean --icon-check

Whether to enable the PNG image verification feature of icon and startWindowIcon.

- true: to enable.

- false (default): not to enable.
ids string --ids For details, see the description of --ids.
definedIds string --defined-ids For details, see the description of --defined-ids.
compression string --compressed-config For details, see the description of --compressed-config.
thread integer --thread For details, see the description of --thread.
ignoreResourcePattern string[] --ignored-file For details, see the description of --ignored-file.
ignoreResourcePathPattern string[] --ignored-path For details, see the description of --ignored-path.
qualifiersConfig object --target-config

Parameter configuration for compilation selection, in JSON format. The supported fields are consistent with the configuration types of --target-config. The field type is a string array, indicating that multiple values can be configured for a configuration type. For example, {"Locale":["zh_CN","en_US"], "Device":["phone"]} is equivalent to Locale[zh_CN,en_US];Device[phone] for --target-config.

NOTE

This field is supported since API version 23.

--compressed-config Parameters

Configure the compilation configuration parameters of texture compression in DevEco Studio. After the compilation, the texture compression configuration file opt-compression.json of restool will be generated in build\default\intermediates\res\default of the module, whose structure is as follows:

{
  "context": {
    // Absolute path of the texture compression library.
    "extensionPath": "xxx\\xxx\\libimage_transcoder_shared.dll"
  },
  "compression": {
    // Whether to enable texture compression for preset media image resources. true to enable; false otherwise.
    "media": {
      "enable": true
    },
    // Filters for preset media image resources.
    "filters": [
      {
        // Texture compression mode. type indicates the conversion type, which can be "astc" or "sut".
        // blocks indicates the conversion extension parameter, which determines the image quality and compression ratio. Currently, only 4x4 is supported.
        "method": {
          "blocks": "4x4",
          "type": "astc"
        },
        // Absolute path of the media image resource file to be compressed.
        "path": [
          "xxx\\MyApplication\\entry\\src\\main\\resources\\base\\media\\startIcon.png",
          "xxx\\MyApplication\\entry\\src\\main\\resources\\base\\media\\icon.png",
        ],
        // Absolute path of the media image resource file to be filtered.
        "exclude_path": [],
        // The image resource file path in path is matched based on the size and resolution. Files that meet the conditions will be compressed.
        "rules_origin": {
          // Two-dimensional array. Each element in the array indicates a size range, in bytes.
          "size": [
            [
              0,
              10485760
            ]
          ],
          // Two-dimensional array. Each element in the array indicates a resolution range. The following indicates that the resolution ranges from 0 × 0 to 1024 × 1024.
          "resolution": [
            [
              {
                "height": 0,
                "width": 0
              },
              {
                "height": 1024,
                "width": 1024
              }
            ]
          ]
        },
        // The image resource file in exclude_path is matched based on the size and resolution. Files that meet the conditions will be filtered out.
        "rules_exclude": {
          "size": [
            [
              0,
              1048576
            ]
          ],
          "resolution": [
            [
              {
                "height": 0,
                "width": 0
              },
              {
                "height": 64,
                "width": 64
              }
            ]
          ]
        }
      }
    ]
  }
}

[h2]Subcommands

Command Description
dump Dumps the resource content in the HAP file in JSON format.

dump

restool dump [-h] [config] filePath

Parameters

Parameter Default Value Allowed Argument Carried Description
-h Yes No Help information.
config Yes No Prints only the qualifiers of resources in the HAP package.

Example:

# Dump all resource information in the HAP file.
restool dump entry.hap
# Dump qualifiers of resources in the HAP file.
restool dump config entry.hap

Example

An example entry directory structure is as follows:

entry/src/main
|    |----resource
|    |    |----base
|    |    |    |----element
|    |    |    |----media
|    |    |    |----profile
|    |    |----rawfile
|    |    |----resfile
|    |----config.json/module.json

[h2]Compiling Resources

There are three resource compilation modes: full resource compilation, incremental resource compilation, and overlay resource compilation. Incremental compilation is available only in preview mode and is used to preview the component effect in the development phase. Full compilation is used to build resource files of a project. Overlay compilation allows resources in a project to be added to existing HAP template resources and compiled resource items to be reused.

  1. Run the following command to compile all resources:

    restool -i entry/src/main -j entry/src/main/module.json -p com.ohos.demo -o out -r out/ResourceTable.txt -f

  2. To compile incremental resources, perform the following steps:

    Step 1: Generate the resource middleware.

    restool -x entry/src/main/resource -o out

    Step 2: Compile the resource middleware.

    restool -i out1 -i out2 -o out -p com.ohos.demo -r out/ResourceTable.txt -j entry/src/main/module.json -f -z

  3. To compile overlay resources, run the following command:

    # hapResource is the path of the decompressed HAP file.
restool -i entry/src/main -i hapResource -j entry/src/main/module.json -p com.ohos.demo -o out -r out/ResourceTable.txt -f

[h2]Fixing the Resource ID

To fix the resource ID, perform the following steps:

Step 1: Create the id_defined.json file. There are two ways to create the file.

restool -i entry/src/main -j entry/src/main/module.json -p com.ohos.demo -o out -r out/ResourceTable.txt --ids out -f
{
    "record" :
    [
        {
            "id" : "0x01000000", // A fixed ID for the resource.
            "name" : "app_name", // Resource name.
            "type" : "string" // Resource type.
        }
    ]
}

Step 2: Fix the resource ID. There are two ways to fix the resource ID.

restool -i entry/src/main -j entry/src/main/module.json -p com.ohos.demo -o out1 -r out1/ResourceTable.txt --defined-ids out/id_defined.json -f
restool -i entry/src/main -j entry/src/main/module.json -p com.ohos.demo -o out1 -r out1/ResourceTable.txt  -f

Error Codes

[h2]11201001 Failed to Load the Dependency Library

Error Message

Failed to load the library 'xxx.dll'.

Symptom

Failed to load the dependency library.

Possible Causes

  1. The path of the dependency library is incorrect or you do not have the permission to access the path.
  2. The third-party dependency library is not installed, the path is incorrect, or you do not have the permission to access the path.
  3. An error is reported on Windows. The files before the xxx.dll path in the user environment variables and system environment variables cannot be accessed. As a result, the environment variables are incorrectly searched during dependency library loading.

Solution

  1. Check whether the dependency library path is correct and whether you have the access permission.
  2. Install the missing third-party dependency library based on the error message. Ensure that the path of the third-party dependency library is correct and you have the access permission.
  3. Add the xxx/HarmonyOS/previewer/common/bin path of the SDK and the path of the dependent library to the first two lines of the environment variable Path. The sequence is not required.

[h2]11203001 Failed to Open the JSON File

Error Message

Failed to open the JSON file 'xxx.json'.

Symptom

Failed to open the JSON file.

Possible Causes

The JSON file path is incorrect, or you do not have the permission to access the JSON file.

Solution

Check whether the JSON file path is correct and whether you have the access permission.

[h2]11203002 Failed to Parse the JSON File

Error Message

Failed to parse the JSON file: incorrect format.

Symptom

Failed to parse the JSON file because the file format is incorrect.

Possible Causes

The JSON file format is incorrect. For example, the JSON file contains unnecessary commas (,).

Solution

Check the JSON file format. For details, see JSON.

[h2]11203003 Unexpected JSON Node Type

Error Message

The value type of node 'xxx' does not match. Expected type: xxx.

Symptom

The type of the xxx node in the JSON file is incorrect.

Possible Causes

The node type in the JSON file is incorrect. For example, the expected type is string, but the actual type is number.

Solution

Check the type of the xxx node in the JSON file.

[h2]11203004 Required Node Missing in JSON

Error Message

The required node 'xxx' is missing.

Symptom

The JSON file does not contain the required xxx node.

Possible Causes

Required nodes, such as name and value, are not configured in the JSON file.

Solution

Check whether the xxx node is missing in the JSON file.

[h2]11203005 Empty Object or Array in JSON

Error Message

The array or object node 'xxx' cannot be empty.

Symptom

The xxx node in the JSON file is an empty object or array.

Possible Causes

The node in the JSON file is empty, for example, the object is set to {} or the array is set to [].

Solution

Check whether the xxx node in the JSON file is empty.

[h2]11203006 Multiple Child Nodes in JSON

Error Message

The node 'xxx' in the JSON file can have only one member.

Symptom

The xxx node in the JSON file can contain only one child node.

Possible Causes

The node in the JSON file contains multiple child nodes.

Solution

Check whether the xxx node contains only one child node.

[h2]11203007 Invalid JSON Node Name

Error Message

Invalid node name 'xxx'. Valid values: ["boolean","color","float","id","intarray","integer","pattern","plural","strarray","string","symbol","theme"].

Symptom

The JSON node name xxx is invalid.

Possible Causes

The name of the node in the JSON file is incorrect and is not within the specified range of ["boolean", "color", "float", "id", "intarray", "integer", "pattern", "plural", "strarray", "string", "symbol", "theme"].

Solution

Check whether the name of the xxx node in the JSON file is within the specified range.

[h2]11204001 Failed to Create a File

Error Message

Failed to create the directory or file 'xxx'.

Symptom

Failed to create the file.

Possible Causes

The file path is incorrect or you do not have the permission to access the file.

Solution

  1. Check that the file path is correct.
  2. Check the file permission. If the file permission is read-only, change it to read and write. The procedure is as follows:
    • Windows: Right-click the file, choose Properties from the shortcut menu, and deselect Read-only.
    • Linux/MacOS: Run the chmod 644 file path command.

      If the error file path is under the build directory for compilation artifacts, you need to manually delete the file that caused the error first, and then modify the permissions of its corresponding source file. For example, if the error path is entry\build\default\intermediates\res\default\resources\base\profile\form_config.json, change the permission of the corresponding source file entry\src\main\resources\base\profile\form_config.json.

[h2]11204003 Failed to Delete the File

Error Message

Failed to delete the directory or file 'xxx'.

Symptom

Failed to delete the file.

Possible Causes

The file path is incorrect or you do not have the permission to access the file.

Solution

  1. Check that the file path is correct.
  2. Check the file permission. If the file permission is read-only, change it to read and write. The procedure is as follows:
    • Windows: Right-click the file, choose Properties from the shortcut menu, and deselect Read-only.
    • Linux/MacOS: Run the chmod 644 file path command.

      If the error file path is under the build directory for compilation artifacts, you need to manually delete the file that caused the error first, and then modify the permissions of its corresponding source file. For example, if the error path is entry\build\default\intermediates\res\default\resources\base\profile\form_config.json, change the permission of the corresponding source file entry\src\main\resources\base\profile\form_config.json.

[h2]11204004 Failed to Copy the File

Error Message

Failed to copy the file from 'xxx' to 'xxx'.

Symptom

Failed to copy the file.

Possible Causes

The file path is incorrect or you do not have the permission to access the file.

Solution

  1. Check that the file path is correct.
  2. Check the file permission. If the file permission is read-only, change it to read and write. The procedure is as follows:
    • Windows: Right-click the file, choose Properties from the shortcut menu, and deselect Read-only.
    • Linux/MacOS: Run the chmod 644 file path command.

      If the error file path is under the build directory for compilation artifacts, you need to manually delete the file that caused the error first, and then modify the permissions of its corresponding source file. For example, if the error path is entry\build\default\intermediates\res\default\resources\base\profile\form_config.json, change the permission of the corresponding source file entry\src\main\resources\base\profile\form_config.json.

[h2]11204005 Failed to Open the File

Error Message

Failed to open the file 'xxx'.

Symptom

Failed to open the file.

Possible Causes

The file path is incorrect or you do not have the permission to access the file.

Solution

  1. Check that the file path is correct.
  2. Check the file permission. If the file permission is read-only, change it to read and write. The procedure is as follows:
    • Windows: Right-click the file, choose Properties from the shortcut menu, and deselect Read-only.
    • Linux/MacOS: Run the chmod 644 file path command.

      If the error file path is under the build directory for compilation artifacts, you need to manually delete the file that caused the error first, and then modify the permissions of its corresponding source file. For example, if the error path is entry\build\default\intermediates\res\default\resources\base\profile\form_config.json, change the permission of the corresponding source file entry\src\main\resources\base\profile\form_config.json.

[h2]11204006 Failed to Read the File

Error Message

Failed to read the file 'xxx'.

Symptom

Failed to read the file.

Possible Causes

  1. The file path is incorrect or you do not have the permission to access the file.
  2. The file is empty.

Solution

  1. Check whether the file path is correct and whether you have the access permission.
  2. Check whether the file is empty.

[h2]11210001 Unknown Command Option

Error Message

Unknown option 'xxx'.

Symptom

Unknown command option.

Possible Causes

The command option is not supported.

Solution

Check whether the command is correct. You can run the -h command to view the command help information and enter the correct command options and parameters.

[h2]11210002 Mandatory Parameters Missing

Error Message

Option 'xxx' requires an argument.

Symptom

Mandatory parameters are missing.

Possible Causes

Mandatory parameters are missing. For example, the input path is not specified for -i/--inputPath.

Solution

Check whether the command is correct. You can run the -h command to view the command help information and enter the correct command options and parameters.

[h2]11210003 Invalid Parameter

Error Message

Invalid argument value 'xxx'.

Symptom

The parameter is invalid.

Possible Causes

All command options must be prefixed with a hyphen (-). The parameters corresponding to the options do not have hyphens. If the hyphen is omitted when you enter an option, the option is processed as a parameter and does not take effect. For example, restool inputPath is processed as a parameter.

Solution

Check whether the command is correct. You can run the -h command to view the command help information and enter the correct command options and parameters.

[h2]11210004 Invalid Input Path

Error Message

Invalid input path 'xxx'.

Symptom

The input path is invalid.

Possible Causes

-The path specified by i/--inputPath is incorrect, or you do not have the access permission.

Solution

Check whether the path parameter is correct and whether you have the access permission.

[h2]11210005 Duplicate Input Path

Error Message

Duplicated input path 'xxx'.

Symptom

The input path is duplicate.

Possible Causes

The same input path is specified for multiple -i/--inputPath options.

Solution

Check whether the path specified by -i/--inputPath is duplicate.

[h2]11210006 Bundle Name Conflict

Error Message

The package names 'xxx' and 'xxx' conflict.

Symptom

The bundle name conflicts.

Possible Causes

The -p/--packageName option is specified multiple times.

Solution

Check whether the -p/--packageName option is specified for multiple times.

[h2]11210007 Invalid Output Path

Error Message

Invalid output path 'xxx'.

Symptom

The output path is invalid.

Possible Causes

-The output path specified by -o/--outputPath does not exist or you do not have the access permission.

Solution

Check whether the path parameter is correct and whether you have the access permission.

[h2]11210008 Output Path Conflict

Error Message

The output paths 'xxx' and 'xxx' conflict.

Symptom

The output path conflicts.

Possible Causes

The -o/--outputPath option is specified multiple times.

Solution

Check whether the -o/--outputPath option is specified for multiple times.

[h2]11210009 Duplicate Resource Header File Path

Error Message

Duplicated resource header path 'xxx'.

Symptom

The resource header file path is duplicate.

Possible Causes

The same resource header file path is specified for multiple -r/--resHeader options.

Solution

Check whether the resource header file path specified by the -r/--resHeader option is duplicate.

[h2]11210010 Module Name Conflict

Error Message

The module names 'xxx' and 'xxx' conflict.

Symptom

The module names conflict.

Possible Causes

The -m/--modules option is specified multiple times.

Solution

Check whether the -m/--modules option is specified multiple times.

[h2]11210011 Duplicate Module Name

Error Message

Duplicated module name 'xxx'.

Symptom

The module name is duplicate.

Possible Causes

-The m/--modules option specifies a duplicate module name, for example, -m entry,entry.

Solution

Check whether the module name specified by -m/--modules is duplicate.

[h2]11210012 Application Configuration File Conflict

Error Message

The paths 'xxx' and 'xxx' of the module.json (in the stage model) or config.json (in the FA model) file conflict.

Symptom

The paths of the application configuration file module.json (of stage model) or config.json (of FA model) conflict.

Possible Causes

The -j/--json option is specified multiple times.

Solution

Check whether the -j/--json option is specified multiple times.

[h2]11210013 Invalid Resource Start ID

Error Message

Invalid start ID 'xxx'. It is out of range.

Symptom

Invalid resource start ID.

Possible Causes

The resource start ID specified by -e/--startId is not within the specified range.

Solution

Check whether the resource start ID is within the range of [0x01000000, 0x06FFFFFF) or [0x08000000, 0xFFFFFFFF).

[h2]11210014 Duplicate Incremental Resource File Path

Error Message

Duplicated append path 'xxx'.

Symptom

The incremental resource file path is duplicate.

Possible Causes

The same incremental resource file path is specified for multiple -x/--append options.

Solution

Check whether the incremental resource file path specified by -x/--append is duplicate.

[h2]11210015 target-config Conflict

Error Message

The target configurations 'xxx' and 'xxx' conflict.

Symptom

The parameters specified by multiple target-config options conflict.

Possible Causes

The --target-config option is specified multiple times.

Solution

Check whether the --target-config option is specified multiple times.

[h2]11210016 Invalid target-config

Error Message

Invalid target configuration argument 'xxx'. The argument format for option --target-config should be like 'Locale[zh_CN,en_US];Device[phone]'.

Symptom

The target-config parameter is invalid.

Possible Causes

--The format of the parameter specified in the target-config option is incorrect.

Solution

Check whether the format of the parameter in the --target-config option is correct, for example, Locale[zh_CN,en_US];Device[phone]. For details about the format, see target-config in Command Options.

[h2]11210017 Invalid System Resource id_defined.json Path

Error Message

Invalid system id_defined.json path 'xxx'.

Symptom

The path of the system resource id_defined.json is invalid.

Possible Causes

The id_defined.json path of the system resource specified by --defined-sysids is incorrect or no access permission is available.

Solution

Check whether the id_defined.json path of the system resource is correct and whether you have the permission to access the path.

[h2]11210018 Duplicate System Resource id_defined.json Path

Error Message

Duplicated system id_defined.json path 'xxx'.

Symptom

--The file path specified by defined-sysids is duplicate.

Possible Causes

The same system resource id_defined.json path is specified for multiple --defined-sysids options.

Solution

Check whether the id_defined.json file path specified by --defined-sysids is duplicate.

[h2]11210019 compressed-config Conflict

Error Message

The compression JSON paths 'xxx' and 'xxx' conflict.

Symptom

The parameters specified by multiple --compressed-config options conflict.

Possible Causes

The --compressed-config option is specified multiple times.

Solution

Check whether the --compressed-config option is specified multiple times.

[h2]11210020 Non-ASCII Parameter Value

Error Message

The argument value 'xxx' is not an ASCII value.

Symptom

The parameter value is not in ASCII format.

Possible Causes

The input or output path parameter contains Chinese characters or other non-ASCII characters.

Solution

Check whether the parameter value contains Chinese characters or non-ASCII characters.

[h2]11210021 Mutually Exclusive Options

Error Message

Options 'xxx' and 'xxx' cannot be used together.

Symptom

Two mutually exclusive options cannot be specified at the same time.

Possible Causes

Two mutually exclusive options are specified, such as -x and --target-config.

Solution

Check whether the command is correct. Do not specify mutually exclusive options. You can run the -h command to view the command help information and input the correct command options and parameters.

[h2]11210022 Empty Package Name

Error Message

The package name is empty. It should be specified with option -p/--packageName.

Symptom

The package name is empty.

Possible Causes

The -p/--packageName option is not specified.

Solution

Check whether the -p/--packageName option is used to specify the package name.

[h2]11210023 Empty Resource Header File Path

Error Message

The resource header path (for example, ./ResourceTable.js, ./ResourceTable.h) is empty. It should be specified with option -r/--resHeader.

Symptom

The resource header file path is empty.

Possible Causes

The resource header file path is not specified by -r/--resHeader.

Solution

Check whether the resource header file path is specified by -r/--resHeader.

[h2]11210024 HAP Path Missing from the dump Command

Error Message

The HAP path of the resource dump command is missing.

Symptom

The dump command does not contain the HAP path.

Possible Causes

The dump command does not specify the path of the HAP.

Solution

Check whether the dump command specifies the HAP path, for example, restool dump xxx/entry.hap.

[h2]11210025 Invalid HAP Path Specified by the dump Command

Error Message

Invalid HAP path 'xxx' in the resource dump command.

Symptom

The HAP path specified in the dump command is invalid.

Possible Causes

The HAP path specified in the dump command is incorrect or you do not have the access permission.

Solution

Check whether the HAP path specified in the dump command is correct and whether you have permission to access it.

[h2]11210026 Invalid Number of Child Threads

Error Message

Invalid thread count 'xxx'. It should be an integer greater than 0.

Symptom

The number of child threads is invalid.

Possible Causes

--The number of child threads specified by the thread option is either a negative number or a decimal.

Solution

Check whether the value of --thread is an integer greater than 0.

[h2]11211001 Output Path Exists

Error Message

The output path exists. Specify option -f/--forceWrite to overwrite.

Symptom

The output path already exists.

Possible Causes

The output path specified by -o/--outputPath already has files, and they cannot be overwritten.

Solution

Check whether the output path has files. You can manually delete the files or specify the -f/--forceWrite option to forcibly overwrite the files.

[h2]11211002 Module Configuration File Path Missing

Error Message

There are multiple input paths, but the path of the module.json (in the stage model) or config.json (in the FA model) file is not specified with option -j/--json.

Symptom

The path of the application configuration file module.json (of stage model) or config.json (of FA model) is missing.

Possible Causes

If only one input path is specified using -i/--inputPath, the restool reads the application configuration file from the parent directory of the input path by default. If multiple input paths are specified, for example, restool -i xxx\AppScope -i xxx\entry\main, you need to specify the path of the application configuration file using -j/--json.

Solution

Check whether the application configuration file path is specified using -j/--json.

[h2]11211003 Invalid Module Type

Error Message

Invalid module type 'xxx'. Valid values: ["entry", "har", "shared", "feature"].

Symptom

The module type is invalid.

Possible Causes

The module type specified in the module.json (of stage model) or config.json (of FA model) file is incorrect. The value is not in the range of ["entry", "har", "shared", "feature"].

Solution

Check whether the module type is within the specified range.

[h2]11211004 Conflict Between Resource Start ID and id_defined.json

Error Message

The start ID 'xxx' specified by option -e/--startId conflict with the IDs in the id_defined.json file.

Symptom

The resource start ID specified by -e/--startId conflicts with the id_defined.json file.

Possible Causes

By default, the start resource ID is 0x01000000. During compilation, the resource IDs increase in ascending order. In addition, restool provides two methods to customize them:

  1. -e/--startId: specifies the start resource ID in the range of [0x01000000, 0x06FFFFFF) or [0x08000000, 0xFFFFFFFF).
  2. Fixing the Resource ID: specifies the resource ID in the id_defined.json file.

If the two methods are used at the same time, the resource IDs calculated in the two methods may be different, causing conflicts.

Solution

Check whether the two methods are used at the same time.

[h2]11211007 Invalid Resource Type in id_defined.json

Error Message

Invalid resource type 'xxx' in the id_defined.json file. Valid values: ["boolean","color","float","id","intarray","integer","pattern","plural","strarray","string","symbol","theme"].

Symptom

The resource type in id_defined.json is invalid.

Possible Causes

The value of type in the id_defined.json file is not within the range of ["boolean", "color", "float", "id", "intarray", "integer", "pattern", "plural", "strarray", "string", "symbol", "theme"].

Solution

Check whether the resource type is within the specified range.

[h2]11211008 Invalid Resource ID in id_defined.json

Error Message

Invalid ID value 'xxx' in the id_defined.json file. It should be a hexadecimal string, match the pattern ^0[xX][0-9a-fA-F]{8}, and be in the scope [0x01000000,0x06FFFFFF] or [0x08000000,0xFFFFFFFF].

Symptom

The resource ID in the id_defined.json file is invalid.

Possible Causes

  1. The resource ID in id_defined.json is not a hexadecimal number.
  2. The ID is not in the range of [0x01000000,0x06FFFFFF] or [0x08000000,0xFFFFFFFF].

Solution

Check whether the resource ID is in hexadecimal format and the value range is [0x01000000,0x06FFFFFF] or [0x08000000,0xFFFFFFFF].

[h2]11211012 Duplicate IDs Defined in id_defined.json

Error Message

The names 'xxx' and 'xxx' in the id_defined.json file define the same ID.

Symptom

Two resources in id_defined.json define the same resource ID.

Possible Causes

The same resource ID is defined for two resources in id_defined.json.

Solution

Check whether the resource ID in the id_defined.json file is unique and whether the value is in the range of [0x01000000,0x06FFFFFF] or [0x08000000,0xFFFFFFFF].

[h2]11211014 Incorrect Module Name

Error Message

The module name 'xxx' is not found in ["yyy","zzz"], which is specified by -m/--modules.

Symptom

The module name in the application configuration file is not in the module name list specified by -m/--modules.

Possible Causes

  1. The module name list specified by -m/--modules is incorrect.
  2. The module name specified by name in the application configuration file module.json (of stage model) or config.json (of FA model) is incorrect.

Solution

Check whether the module name list specified by -m/--modules contains the module name specified by name in the application configuration file.

[h2]11211101 Invalid Resource File

Error Message

Failed to scan resources: invalid path 'xxx'.

Symptom

Resource scanning fails because the resource file is invalid.

Possible Causes

The resource file does not meet the requirements. For example:

  1. rawfile is expected to be a folder, but it is actually a file.
  2. base/element is expected to contain only JSON files, but actually contains folders.

Solution

Check whether the resource file type is correct. For details, see Resource Categories.

[h2]11211103 Invalid Qualifier Directory

Error Message

Invalid qualifier key 'xxx'. It should match the pattern of the qualifiers directory, for example zh_CN or en_US.

Symptom

The qualifier directory is invalid.

Possible Causes

The qualifier directory name is incorrect.

Solution

Check whether the qualifiers directory name is correct. For details about the naming rules, see Qualifiers Directory.

[h2]11211104 Invalid Resource Group Directory

Error Message

Invalid resource directory name 'xxx'. Valid values: ["element","media","profile"].

Symptom

The resource group directory name is invalid.

Possible Causes

The resource group directory name in the qualifiers directory is incorrect and is not in the range of ["element", "media", "profile"].

Solution

Check whether the qualifiers directory contains only resource group directories: element, media, and profile.

[h2]11211106 Invalid Translation Status

Error Message

Invalid translation priority value 'xxx'. Valid values: ["code","translate","LT","customer"].

Symptom

Invalid translation status.

Possible Causes

The translation status attribute priority of the translatable attribute attr of the string or plural resource is incorrectly configured and is not in the range of ["code", "translate", "LT", "customer"].

Solution

Check whether the value of priority is correct. For details, see Using the attr Attribute for Resource Translation.

[h2]11211107 element Type Not Supported

Error Message

Unsupported element resource type 'xxx'. Valid values: ["integer","string","strarray","intarray","boolean","color","theme","plural","float","pattern","symbol"].

Symptom

The element type is not supported.

Possible Causes

The JSON resource file in the element directory supports the following resource types: "integer", "string", "strarray", "intarray", "boolean", "color", "theme", "plural", "float", "pattern", and "symbol". "id" is not supported.

Solution

Check whether the element type is correct. For details, see Resource Group Directories

[h2]11211108 Invalid Color Value

Error Message

Invalid color value 'xxx' of the resource 'xxx'. It can only reference '$color:xxx' or be '#rgb', '#argb', '#rrggbb', or '#aarrggbb'.

Symptom

The color value is invalid.

Possible Causes

The color resource supports only the following formats:

  1. Referencing other color resources. For example, $color:xxx references the application's color resource, or $ohos:color:xxx references the system color resource.
  2. RGB color value starting with #, for example, #rgb, #argb, #rrggbb, and #aarrggbb.

Solution

Check whether the color resource is in the correct reference format or RGB format.

[h2]11211109 Invalid Resource Reference

Error Message

Invalid resource reference $xxx:xxx. Supported reference: $(ohos:)?xxx:xxx.

Symptom

The resource reference is invalid.

Possible Causes

Resource reference applies only to resources of the same type. For example, in string.json, you can use $string:xxx to reference the application's string resources or use $ohos:string:xxx to reference system string resources. However, you cannot use $integer:xxx to reference integer resources.

Solution

Check whether the resource reference mode is correct.

[h2]11211110 Empty parent in theme Resource

Error Message

The parent value of resource 'xxx' is empty. It should be a valid resource name.

Symptom

The parent value of the theme resource is empty.

Possible Causes

The parent property of the theme resource is optional. Its value must be the name of another theme resource and cannot be an empty string. The following is a correct example:

{
  "theme": [
    {
      "name": "base",
      "value": [
        {
          "name": "width",
          "value": "wrap_content"
        },
        {
          "name": "height",
          "value": "wrap_content"
        },
        {
          "name": "size",
          "value": "25dp"
        }
      ]
    },
    {
      "name": "child",
      "parent": "base",
      "value": [
        {
          "name": "noTitle",
          "value": "yes"
        }
      ]
    }
  ]
}

Two theme resources base and child are declared. base does not contain the parent property, and the parent property of the child resource is set to "base".

Solution

Check whether the parent property of the theme resource is empty. If the parent property is not required, delete it.

[h2]11211111 Excessive array Resource Length

Error Message

The array resource 'xxx' is too large. The total length of the value of the array elements cannot exceed 65535.

Symptom

The length of the array resource is too long.

Possible Causes

The total length of an array resource exceeds 65535 bytes.

Solution

Check whether the length of the array resource is too long. If the length is too long, split the array resource into multiple array resources.

[h2]11211112 Invalid plural Resource Type

Error Message

Invalid quantity 'xxx' of the plural resource 'xxx'. Valid values: ["zero","one","two","few","many","other"].

Symptom

The plural resource type is invalid.

Possible Causes

The value of the quantity property of the plural resource is incorrect and falls outside the range of ["zero", "one", "two", "few", "many", "other"].

Solution

Check whether the plural resource type is correct. For details, see Singular/Plural Form Selection.

[h2]11211113 Duplicate plural Resource Type

Error Message

Duplicated quantity 'xxx' of the plural resource 'xxx'.

Symptom

The plural resource type is duplicate.

Possible Causes

The same type is declared repeatedly in the plural resource. For example, the one type is declared repeatedly for eat_apple in the following error example:

{
  "plural": [
    {
      "name": "eat_apple",
      "value": [
        {
          "quantity": "one",
          "value": "%d apple"
        },
        {
          "quantity": "one",
          "value": "%d apple"
        },
        {
          "quantity": "other",
          "value": "%d apples"
        }
      ]
    }
  ]
}

Solution

Check whether the plural resource type is duplicate. For details, see Singular/Plural Form Selection.

[h2]11211114 other Type Missing in Plural Resource

Error Message

The plural resource 'xxx' should contain the 'other' quantity.

Symptom

The resource must contain the other type.

Possible Causes

The plural resource does not contain the other type.

Solution

Check whether the plural resource contains the other type. For details, see Singular/Plural Form Selection.

[h2]11211115 Invalid symbol Resource

Error Message

Invalid value 'xxx' of the symbol resource 'xxx'. It should be in the scope [0xF0000,0xFFFFF] or [0x100000,0x10FFFF].

Symptom

The symbol resource value is invalid.

Possible Causes

The symbol resource value is not within the range of [0xF0000,0xFFFFF] or [0x100000,0x10FFFF].

Solution

Check whether the symbol resource value is within the specified range.

[h2]11211116 Invalid Resource Name

Error Message

Invalid resource name 'xxx'. It should match the pattern [a-zA-Z0-9_].

Symptom

The resource name is invalid.

Possible Causes

The resource name must match the [a-zA-Z0-9_] rule and can contain only uppercase letters, lowercase letters, digits, and underscores (_).

Solution

Check whether the resource name matches the [a-zA-Z0-9_] rule.

[h2]11211117 Duplicate Resource Definition

Error Message

Resource 'xxx' conflict. It is first declared at 'xxx' and declared again at 'xxx'.

Symptom

The resource definition is duplicate.

Possible Causes

Resources of the same type and name are defined in multiple places, causing conflicts.

Solution

Check whether the resource is defined repeatedly. If yes, change the resource name or delete the duplicate resource.

[h2]11211118 Resource ID Exceeds Maximum

Error Message

The resource ID 'xxx' exceeds the maximum ID 'xxx'.

Symptom

The resource ID exceeds the maximum value.

Possible Causes

The application resource ID is in the range of [0x01000000,0x06FFFFFF] or [0x08000000,0xFFFFFFFF]. If there are too many resources or a large resource start ID is specified, the ID may overflow and exceed the maximum value 0x06FFFFFF or 0xFFFFFFFF.

Solution

  1. Delete unnecessary resources.
  2. Specify a smaller resource start ID.

[h2]11211120 Referenced Resource Not Defined

Error Message

The resource reference '$xxx:xxx' is not defined.

Symptom

The referenced resource is not defined.

Possible Causes

  1. The referenced resource does not exist. For example, the resource has been deleted or renamed.
  2. The directory where the referenced resource is located is not specified as the input path using -i/--inputPath.

Solution

  1. Check whether the resource reported in the error information exists.
  2. Check whether the parent directory of resources where the resource is located is specified as the input path using -i/--inputPath. For example, if the resource in the error information is defined in xxx/entry/src/main/resources/base/element/string.json, you need to specify xxx/entry/src/main as the input path.

[h2]11211124 Failed to Parse the resources.index File

Error Message

Failed to parse the resources.index file.

Symptom

The resources.index file parsing fails.

Possible Causes

The format of resources.index is incorrect. For example, the content is empty or the beginning of the file does not contain 128-byte version information.

Solution

Check the source of the resources.index file and ensure that the file is generated by restool.

[h2]11212001 Failed to Parse the HAP

Error Message

Failed to parse the HAP.

Symptom

The HAP parsing fails.

Possible Causes

The format of the HAP file is incorrect. For example, it fails to be decompressed after being compressed multiple times.

Solution

Check the format of the HAP file. Ensure that the HAP is generated by the SDK without any modification, such as compression and decompression.