Validation Rules

Every rule CFXAdmin applies to cfxainstall.yml manifests, with error codes and fixes. Use this reference to debug manifest errors and understand graceful fallback behaviour.

Overview

CFXAdmin validates your manifest before executing any tasks. Validation produces two types of results:

error — Hard failure. The manifest is rejected and CFXAdmin falls back to the next tier in the precedence model. No manifest tasks run, but the resource is still installed.
warning — Advisory. The manifest continues executing; the issue is logged. Worth fixing, but not blocking.

ℹ

Validation never blocks an install Errors trigger a graceful fallback through the three-tier precedence model. Your users always get a working install — they just won't get your manifest's custom steps if it fails validation.

Schema Rules

Code	Severity	Condition	Fix
`MANIFEST-001`	error	`schemaVersion` is missing, not a valid version string, or has an unsupported major version (only major version `1` is supported).	Set `schemaVersion: "1.0"`.
`MANIFEST-001`	warning	`schemaVersion` minor version is newer than expected (e.g. `"1.3"` on an older CFXAdmin build).	No action needed — newer minor versions are forward-compatible. Some fields may be ignored on older builds.
`MANIFEST-002`	error	`id` field is missing or empty.	Set `id` to your resource's folder name, e.g. `id: qb-multicharacter`.
`MANIFEST-003`	error	`name` field is missing or empty.	Set `name` to a human-readable display name.

Feature Flag Rules

Code	Severity	Condition	Fix
`MANIFEST-010`	warning	An entry in `requiresFeatures` is not a known feature flag.	Remove the unknown flag or check for a typo. Known flags: `sql`, `lua_patch`, `comment_line`, `provider_replace`.

Task Rules

Code	Severity	Condition	Fix
`MANIFEST-020`	error	A task has no `action` field.	Add an `action` field to the task.
`MANIFEST-021`	error	A task has an unknown `action` value.	Valid actions: `install_option`, `operation`, `add_note`, `show_warning`, `show_manual_step`, `require_confirmation`, `abort_with_message`, `get_dependency`.
`MANIFEST-031`	warning	`add_note` task has neither `message` nor `description`.	Add a `message` field with the note text.

Install Option Rules

Code	Severity	Condition	Fix
`MANIFEST-022`	error	`install_option` task has no `key`.	Add a unique `key` field, e.g. `key: remove_qb_spawn`.
`MANIFEST-023`	error	Two `install_option` tasks share the same `key`.	Give each option a unique key.
`MANIFEST-024`	warning	`install_option` has no `label`.	Add a `label` so users know what the option does.
`MANIFEST-025`	error	`install_option` has an unknown `type`.	Valid types: `boolean`, `choice`, `string`.
`MANIFEST-026`	error	`install_option` with `type: choice` has no `choices`.	Add a `choices` list with at least one entry.

Operation Rules

Code	Severity	Condition	Fix
`MANIFEST-040`	error	`operation` task has no `operationType`.	Add an `operationType` field.
`MANIFEST-041`	error	Unknown `operationType` value.	Valid types: `remove_resource`, `patch_lua_value`, `patch_text_replace`, `comment_line`, `uncomment_line`, `ensure_line`, `ensure_folder`, `copy_file`, `move_file`, `delete_file`.
`MANIFEST-042`	error	Operation requires `target` but it is missing.	Add `target: resource-name`.
`MANIFEST-043`	error	Operation requires `file` but it is missing.	Add `file: relative/path/to/file.lua`.
`MANIFEST-044`	error	`patch_lua_value` requires `luaPath` but it is missing.	Add `luaPath: Config.YourKey`.
`MANIFEST-045`	error	`patch_lua_value` requires `value` but it is missing.	Add `value: "true"` or the appropriate Lua value.
`MANIFEST-046`	error	`patch_text_replace` requires `pattern` but it is missing.	Add `pattern: "text to find"`.
`MANIFEST-047`	error	`patch_text_replace` requires `replacement` but it is missing.	Add `replacement: "replacement text"` (may be an empty string to delete the matched text).
`MANIFEST-048`	error	`comment_line` or `uncomment_line` requires `value` (a substring to match).	Add `value: "@qb-apartments/config.lua"` (or your target substring).
`MANIFEST-049`	error	`copy_file` or `move_file` requires both `source` and `destination`.	Add both `source` and `destination` fields.
`MANIFEST-050`	error	`operationType: run_script` is used.	`run_script` is blocked and not supported. Use `patch_lua_value` or `patch_text_replace` for config changes.
`MANIFEST-051`	error	`insert_after_anchor` or `insert_before_anchor` is missing `anchor`.	Add `anchor: "substring to find"`.
`MANIFEST-052`	error	Anchor insert operation is missing `content`.	Add `content: \|` followed by the lines to insert.
`MANIFEST-053`	error	A server.cfg operation is missing `ensureTarget`.	Add `ensureTarget: "resource-name"`.
`MANIFEST-054`	error	`add_ensure_after` is missing `afterEnsure`.	Add `afterEnsure: "resource-name"`.
`MANIFEST-055`	error	`add_ensure_before` is missing `beforeEnsure`.	Add `beforeEnsure: "resource-name"`.
`MANIFEST-056`	error	`set_load_order_group` has a missing or invalid `group`.	Valid groups: `libs`, `framework`, `jobs`, `default`.
`MANIFEST-057`	error	`set_convar` is missing `key`.	Add `key: "YourConvarKey"`.
`MANIFEST-058`	error	`set_convar` is missing `value`.	Add `value: "your_value"`.
`MANIFEST-059`	error	`occurrence` field has an invalid value.	Valid values: `first`, `last`, or `index:N` (e.g. `index:2`).

Path Safety Rules

These rules block operations that could escape the resource root or access disallowed network hosts.

Code	Severity	Condition	Fix
`MANIFEST-060`	error	A `file`, `source`, or `destination` path contains `..` or is an absolute path.	Use paths relative to the resource root. Example: `config/config.lua` not `../other/config.lua`.
`MANIFEST-060b`	error	`get_dependency` is missing `name`.	Add `name: "dep-name"`.
`MANIFEST-061`	error	`get_dependency` is missing `url`.	Add `url: "https://github.com/..."`.
`MANIFEST-062`	error	`get_dependency` URL host is not on the allowed list, or the URL is invalid.	Only `github.com`, `raw.githubusercontent.com`, and `codeload.github.com` are allowed.

Flow Control Rules

Code	Severity	Condition	Fix
`MANIFEST-070`	warning	`show_warning` has no `message`.	Add a `message` field.
`MANIFEST-071`	error	`show_manual_step` is missing `message`.	Add a `message` field with the operator instruction.
`MANIFEST-072`	error	`require_confirmation` is missing `message`.	Add a `message` field with the confirmation prompt.
`MANIFEST-073`	error	`abort_with_message` is missing `message`.	Add a `message` field explaining why the install cannot proceed.

Runtime Error Codes

These codes appear in CFXAdmin's diagnostic log when manifest tasks fail at execution time (after validation has already passed).

Code	When it fires
`INST-MANIFEST-ANCHOR-NOTFOUND`	An anchor string was not found in the target file and `ifMissing` is not `skip`.
`INST-MANIFEST-ENSURE-ORDER`	An `add_ensure_after/before` anchor was not found — ensure was appended/prepended as fallback.
`INST-MANIFEST-CONVAR-SET`	A `set_convar` operation failed.
`INST-MANIFEST-DEPENDENCY-DOWNLOAD`	A `get_dependency` download or extraction failed.
`INST-MANIFEST-DEPENDENCY-INVALID`	A downloaded dependency is not a valid FiveM resource, the URL host is disallowed, or required fields are missing.
`INST-MANIFEST-ABORT`	An `abort_with_message` task triggered — execution stopped at that point.

Fallback Behaviour

When validation produces any errors, CFXAdmin logs them and falls back gracefully through the three-tier precedence model:

The resource is still installed (ZIP extracted, ensure line added to server.cfg).
Provider replacement, auto-wire, and SQL migrations still run.
Manifest-specific install tasks are skipped.
The install summary shows a notice that the manifest was skipped.

✦

Debugging tip Validation error codes are included in CFXAdmin's diagnostic log. Enable diagnostics in CFXAdmin Settings and look for manifest.validate_fail events to see the exact error list for your manifest.