> ## Documentation Index
> Fetch the complete documentation index at: https://docs.liteshop.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Validation errors

> The codes Liteshop reports when it checks a Site Bundle, what each one means, and how to fix it.

Liteshop validates every Site Bundle before it publishes it. Each problem is a
diagnostic with a stable `code`, the `path` of the file or manifest property
concerned, a `message`, and a `repair` instruction. Errors block publishing.
Warnings don't block publishing.

To fix a Site, apply every repair instruction, rebuild the complete bundle, and
upload it again. If an AI assistant built the Site, paste the complete
diagnostics into the conversation.

## Bundle

These codes concern the archive and its files.

| Code | Meaning | Fix |
| - | - | - |
| `BUNDLE_REQUIRED_FILE_MISSING` | `index.html` or `liteshop.json` isn't at the root of the bundle. | Zip the contents of your build folder, not the folder itself. |
| `BUNDLE_ZIP_INVALID` | The ZIP file can't be read. | Create a new ZIP file with the Site files at the archive root. |
| `BUNDLE_SOURCE_UNSUPPORTED` | The upload isn't a folder or a `.zip` file. | Upload a ZIP file. |
| `BUNDLE_ARCHIVE_TOO_LARGE` | The ZIP file is larger than 32 MB. | Compress or remove large assets. |
| `BUNDLE_EXPANDED_SIZE_EXCEEDED` | The files add up to more than 50 MB. | Compress or remove large assets. |
| `BUNDLE_FILE_TOO_LARGE` | One file is larger than 10 MB. | Compress, resize, or remove the file. |
| `BUNDLE_TOO_MANY_FILES` | The bundle has more than 2,000 files. | Remove generated, duplicate, or unused files. |
| `BUNDLE_COMPRESSION_RATIO_EXCEEDED` | A file compresses more than 100 times. | Re-encode or remove the file. |
| `BUNDLE_FILE_TYPE_UNSUPPORTED` | A file has an extension Liteshop doesn't serve. | Use a supported type; see [Site Bundle](https://docs.liteshop.me/reference/site-bundle.md#files). |
| `BUNDLE_MIME_MISMATCH` | A file's contents don't match its extension, for example a JPEG named `.png`. | Re-export the file in the format its extension names. |
| `BUNDLE_PATH_INVALID` | A path is unsafe, for example it contains `..` or a backslash. | Use plain relative paths. |
| `BUNDLE_PATH_COLLISION` | Two paths differ only by letter case. | Rename one file and update its references. |
| `BUNDLE_DUPLICATE_PATH` | The ZIP file contains the same path twice. | Keep one copy of each file. |
| `BUNDLE_SYMLINK_FORBIDDEN` | The bundle contains a symbolic link. | Replace it with a regular file. |
| `BUNDLE_EXECUTABLE_FORBIDDEN` | A file has executable permissions. | Remove the permissions before you create the ZIP file. |
| `BUNDLE_SVG_UNSAFE` | An SVG file contains scripts, event handlers, or external references. | Remove them from the SVG file. |
| `BUNDLE_XML_UNSAFE` | An XML file contains a script, embedded content, or a stylesheet instruction. | Keep XML files to data, such as a sitemap. |

## Manifest

These codes concern `liteshop.json`. The `path` points to the property, for
example `/capabilities/forms/0/fields/1`.

| Code | Meaning | Fix |
| - | - | - |
| `SPEC_JSON_INVALID` | `liteshop.json` isn't valid JSON. | Remove comments and trailing commas. |
| `SPEC_REQUIRED_PROPERTY` | A required property is missing. | Add it. |
| `SPEC_UNKNOWN_PROPERTY` | A property isn't part of the Site Specification. | Remove it or use a documented property. |
| `SPEC_INVALID_TYPE` | A value has the wrong type, for example a string instead of a number. | Use the type the message names. |
| `SPEC_INVALID_VALUE` | A value isn't one of the allowed values. | Use a documented value. |
| `SPEC_PATTERN_MISMATCH` | An ID, locale, or path has the wrong format. | IDs use lowercase kebab case, such as `contact-form`. |
| `SPEC_CONSTRAINT_VIOLATION` | A Catalogue Item declares both `image` and `images`. | Keep only `images`, with the main image first. |
| `SPEC_DUPLICATE_ID` | Two entries share an ID. | Give each entry a unique, stable ID. |
| `SPEC_DEFAULT_LOCALE_UNSUPPORTED` | `site.defaultLocale` isn't in `site.supportedLocales`. | Add it to `supportedLocales`. |
| `SPEC_DEFAULT_LOCALE_TEXT_MISSING` | A label has no text in the default language. | Add the default-language text. |
| `SPEC_TIMEZONE_INVALID` | `site.timezone` isn't a supported IANA time zone. | Use a name such as `Europe/Paris`. |
| `SPEC_SELECT_OPTIONS_REQUIRED` | A `select` field has no options. | Add at least one option. |
| `SPEC_FIELD_OPTIONS_UNSUPPORTED` | A field that isn't a `select` declares options. | Remove the options or change the type to `select`. |
| `SPEC_FIELD_RANGE_INVALID` | A field's `minLength` is greater than its `maxLength`. | Correct the limits. |
| `SPEC_UNKNOWN_RESOURCE` | An Offer consumes a Resource that isn't declared. | Use a declared Resource ID. |
| `SPEC_BOOKING_WINDOW_INVALID` | An Offer's minimum advance is greater than its maximum advance. | Correct the two values. |
| `SPEC_HOURS_INVALID` | Opening hours end before they start. | Set `to` later than `from`; use `24:00` for midnight. |
| `SPEC_HOURS_TOO_SHORT` | Opening hours are shorter than one slot. | Lengthen the hours or shorten `durationMinutes`. |
| `SPEC_HOURS_OVERLAP` | Two opening hours overlap on the same day. | Merge them into one entry. |
| `SPEC_COLLECTION_ITEM_UNKNOWN` | A collection lists an item that isn't declared. | List only declared item IDs. |
| `SPEC_BASE_DEPLOYMENT_MISMATCH` | An update doesn't name the live version in `baseDeployment`. | Set `baseDeployment` to the value in the repair message. See [Publish an update](https://docs.liteshop.me/develop/deploy.md#publish-an-update). |

## Frontend

These codes concern your HTML and JavaScript.

| Code | Meaning | Fix |
| - | - | - |
| `FRONTEND_ENTRY_MISSING` | A file named in `frontend` doesn't exist. | Add the file or correct the path, with matching case. |
| `FRONTEND_REFERENCE_MISSING` | A page or script references a file that isn't in the bundle. | Add the file or correct the path, with matching case. |
| `FRONTEND_REFERENCE_INVALID` | A file uses the reserved `/_liteshop/` path. | Keep Site files outside `/_liteshop/`; only reference `/_liteshop/sdk/v1.js`. |
| `FRONTEND_EXTERNAL_RUNTIME_FORBIDDEN` | A page loads a script or stylesheet from another website. | Bundle the file, or remove the integration. |
| `FRONTEND_FORM_HANDLER_MISSING` | A declared Form has no `liteshop.forms.submit` call. | Call `liteshop.forms.submit("FORM_ID", values)` with the ID as a literal string. |
| `FRONTEND_FORM_UNDECLARED` | The code submits a Form that `liteshop.json` doesn't declare. | Declare the Form, or use a declared Form ID. |
| `FRONTEND_OFFER_UNDECLARED` | The code uses an Offer that isn't declared. | Declare the Offer, or use a declared Offer ID. |
| `FRONTEND_CATALOGUE_ITEM_UNDECLARED` | The code requests a Catalogue Item that isn't declared. | Declare the item, or use a declared item ID. |
| `FRONTEND_CATALOGUE_IMAGE_INVALID` | A Catalogue Item's image isn't a PNG, JPEG, WebP, or AVIF file in the bundle. | Add the image or correct the path. |
| `FRONTEND_SDK_SCRIPT_MISSING` | A page calls the `liteshop` global before it loads `/_liteshop/sdk/v1.js`. | Load the SDK script before your script, or import `@liteshop.ai/sdk`. |
| `FRONTEND_SDK_METHOD_UNSUPPORTED` | The code calls a method the SDK doesn't have. | Use only the methods in the [SDK reference](https://docs.liteshop.me/reference/sdk.md). |
| `FRONTEND_NATIVE_FORM_POST_UNSUPPORTED` | A form posts to the server with `method="post"`. | Remove `method` and `action`, and submit with the SDK. |
| `FRONTEND_JAVASCRIPT_INVALID` | A JavaScript file has a syntax error. | Fix the syntax. |
| `FRONTEND_JAVASCRIPT_IMPORT_INVALID` | A script loads a file that isn't `.js` or `.mjs`. | Load a bundled JavaScript file. |
| `FRONTEND_DYNAMIC_IMPORT_UNSUPPORTED` | `import()` uses a computed path. | Use a literal path, such as `import("./chart.js")`. |
| `FRONTEND_IMPORT_MAP_INVALID` | An import map isn't a JSON object. | Fix or remove the import map. |

## Security

| Code | Severity | Meaning | Fix |
| - | - | - | - |
| `SECURITY_INLINE_SCRIPT_FORBIDDEN` | Error | An element uses an HTML event handler such as `onclick`. | Move the code into a script and use `addEventListener`. |
| `SECURITY_INLINE_SCRIPT_LIMIT` | Error | A page has more than 100 inline scripts. | Move scripts into bundled files. |
| `SECURITY_RUNTIME_FORBIDDEN` | Error | A page contains an `iframe`. | Remove it; embedded third-party content isn't supported. |
| `SECURITY_RUNTIME_DISCOURAGED` | Warning | Code appears to use `fetch`, WebSockets, workers, service workers, or `eval`. | If your own code uses the feature, remove it: the Site's security policy blocks it. Framework code often mentions these APIs without using them; you can ignore the warning in that case. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.