What errors can occur?¶
Overview¶
When uploading installation guidance bundles through the compatibility data update system, virus scan and validation checks are performed to ensure bundle integrity and compliance. This topic provides a comprehensive list of possible upload and validation errors, their conditions, and corresponding error messages to help developers troubleshoot bundle upload issues.
Error categories¶
The validation process checks for errors in the following categories:
- Virus Scan Errors: Issues that occur before bundle validation is completed
- Bundle-Level Errors: Issues with the bundle file itself
- Rego File Errors: Problems with Open Policy Agent (.rego) files
- JSON File Errors: Issues with JSON configuration files
- Manifest File Errors: Problems with manifest files
Bundle Upload and Validation Error Reference¶
| Error Type | Condition | Error Code | Error Message |
|---|---|---|---|
| Virus Detected | Uploaded Virus infected Bundle | N/A |
"Bundle rejected - virus detected" |
| Invalid Bundle Extension | Bundle file does not have a .tar.gz extension | bundle.invalidExtension |
"Invalid file format. Upload a valid .tar.gz bundle file." |
| Bundle Extraction Failure | Bundle cannot be untarred (corrupt or invalid format) | bundle.extractionFailed |
"File could not be extracted. Check the file and try again." |
| Bundle Size Exceeded | Bundle file size exceeds allowed limit | bundle.sizeExceeded |
"Bundle size too large. Upload a bundle file smaller than 2MB." |
| Forbidden Characters in Bundle/File Name | Bundle or file name contains forbidden characters | bundle.invalidFileName |
"File name contains forbidden or unsupported characters. Rename the file and upload again." |
| Unsupported File Types | Files with extensions other than .rego, .json, or .manifest found in the bundle | bundle.subFile.unsupportedFileType |
"Other file formats found in bundle. Only .rego, .json, and .manifest files allowed." |
| Nested Directories Detected | Bundle contains nested directories (should be flat) | bundle.nestedDirectories |
"Nested directories detected. Bundle must have a flat file structure." |
| Hidden/System Files Detected | Bundle contains hidden/system files (e.g., .DS_Store, Thumbs.db) | bundle.hiddenFiles |
"Bundle contains hidden or system files which are not allowed." |
| Empty Archive | Bundle archive is empty after extraction | bundle.emptyArchive |
"Bundle archive does not contain any files." |
| Multiple .rego Files | More than one .rego file found in the bundle | bundle.rego.multiple |
"Multiple .rego files found. Include only one .rego file in your bundle and upload again." |
| Missing Mandatory .rego File | No .rego file found in the bundle | bundle.rego.missing |
"Missing .rego file. Ensure your bundle contains a .rego file and upload again." |
| Invalid .rego File Format | .rego file is present but cannot be parsed by OPA | bundle.rego.invalidFormat |
"Invalid schema of .rego file. Check and try again." |
| Rego Syntax Error | .rego file contains syntax errors that prevent parsing | bundle.rego.syntaxError |
"The rego file contains syntax errors. Check the code structure and fix any syntax issues." |
| Missing Required Rules/Elements in Rego | .rego file is missing essential rules or policy elements required for proper functioning | bundle.rego.missingRule |
"The rego file is missing essential rules or elements required for validation." |
| Deprecated or Unsupported OPA Version | .rego file uses deprecated or unsupported OPA version. Only OPA v1 is supported | bundle.rego.deprecatedVersion |
"Rego file uses version that are not supported. Only OPA v1 is supported." |
| Multiple .json Files | More than one .json file found in the bundle | bundle.json.multiple |
"Multiple .json files found. Include at most one .json file in your bundle and upload again." |
| Invalid .json File Format | .json file is present but does not match the required JSON schema | bundle.json.invalidFormat |
"Invalid schema of .json file. Check and try again." |
| Duplicate Keys in JSON | .json file contains duplicate keys | bundle.json.duplicateKeys |
".json file contains duplicate keys which are not allowed." |
| Missing Mandatory .manifest File | No .manifest file found in the bundle | bundle.manifest.missing |
"Missing .manifest file. Ensure your bundle contains a .manifest file and upload again." |
| Multiple .manifest Files | More than one .manifest file found in the bundle | bundle.manifest.multiple |
"Multiple .manifest files found. Include exactly one .manifest file in your bundle and upload again." |
| Invalid .manifest File Format | .manifest file is present but does not match the required format or schema | bundle.manifest.invalidFormat |
"Invalid format of .manifest file. Check and try again." |
| File Not UTF-8 Encoded | Any file is not UTF-8 encoded | bundle.file.notUtf8 |
"File must be UTF-8 encoded." |
Best practices¶
To avoid common validation errors:
- Bundle Structure: Ensure your bundle has a flat file structure with no nested directories
- File Types: Include only .rego, .json, and .manifest files in your bundle
- File Encoding: Use UTF-8 encoding for all files
- File Naming: Avoid special characters in file names
- Bundle Size: Keep bundle size under 2MB
- Required Files: Always include exactly one .rego file and one .manifest file
- Optional Files: Include at most one .json file for translation data. This .json file supports multilingual configurations; however, English is currently the only supported language.
- Virus Scan Completion: Wait until the virus scan finishes successfully before reviewing validation results in the Installation Guidance section.