Ship it
Linting
featurevisor lint checks every definition and test spec before anything is built. It catches a misspelled attribute, a value outside its schema or a feature that requires itself, and names the file, the path and usually the fix. Run it on every pull request, so a mistake is caught in review rather than by users.
Run it#
npx featurevisor lintMisspell the plan attribute in the payingAccounts segment, and lint stops with exit code 1:
segments/payingAccounts.yml => Error: Unknown attribute "plann". Did you mean "plan"? Path: conditions.0.attributeFix every error it reports, then run it again until it passes. A file that cannot be parsed is reported with its line and column. Add --verbose to see the parser's stack while investigating.
What it checks#
- Structure: every definition and spec has the fields its kind allows, of the right type.
- References: attributes, segments, features, global variables and schemas exist, with a suggestion when a name is close to one that does.
- Values: defaults, overrides, mutations and test expectations match their schemas.
- Operators: each operator suits the declared type of what it compares.
- Dates: timestamp attributes and variables, declared with
format: date-time, accept only the six date and presence operators, and theirenumandconstvalues must be timestamps. String schemas withformat: date-timevalidate timestamp values. - Context: test values that do not match declared attributes produce warnings, not errors.
- Dependencies: conditions do not form a cycle or a chain too deep to evaluate.
- Archived definitions: no active definition, spec or target references an archived feature, global variable, segment or attribute, including the keys of sticky values in specs. Archived definitions are left out of datafiles, so such a reference would silently stop matching. An archived definition is checked for its shape only. Its own references are not resolved, so what it used can change or be deleted.
- Deprecated definitions: a reference to a deprecated feature, feature variable or global variable from an active definition is a warning, not an error.
- Untyped values: a condition reading a
jsonvariable, or inside an object declared withoutproperties, is anuntyped_conditionwarning, and a list mixing strings and numbers amixed_listwarning, not errors. Their contents have no single declared type to compare with. - Metadata: each definition's metadata has the shape Featurevisor reads, and matches the project's
metadataSchema. An open deadline that is overdue or due today is a warning, never an error. - Patterns: regular expressions stay in the portable subset and cannot backtrack exponentially.
- Project rules: tags, reserved keys and the optional lint rules in your configuration, such as the kinds of condition each location accepts.
Lint does not run your tests, and test does not lint first. Run both, lint first, so a broken spec is reported as a broken spec rather than as a failing assertion:
npx featurevisor lintnpx featurevisor testIn CI, run them as separate steps that stop on failure, or join them with &&.
build does not lint either. A build can succeed with definitions lint would reject, such as an invalid date operand, so a successful build does not mean the project is valid. Lint before you build too.
Lint part of a project#
--key-pattern takes a regular expression matched against keys, case sensitively, and --entity-type narrows it to one kind:
npx featurevisor lint \ --key-pattern=checkout \ --entity-type=featureThe pattern is not anchored, so checkout also matches checkoutSettings. Use ^checkout$ for exactly one key.
The entity types are attribute, segment, feature, variable, schema, target, test and scenario. With npm scripts, pass options after --, as in npm run lint -- --key-pattern=checkout.
JSON output#
Pass --json for output a script can read, and --pretty to indent it:
npx featurevisor lint --json --pretty{ "errors": [ { "filePath": "segments/payingAccounts.yml", "entityType": "segment", "key": "payingAccounts", "message": "Unknown attribute \"plann\". Did you mean \"plan\"?", "path": ["conditions", 0, "attribute"], "code": "custom" } ], "warnings": []}The exit code is the same as without --json: 1 when there are errors, 0 when there are none. Warnings alone never fail, unless --fail-on names them.
Fail on warnings#
Warnings never change the exit code. To make one fail lint, name its code with --fail-on, and repeat the option for more:
npx featurevisor lint --fail-on=deadline_overdueEach warning with that code prints and counts as an error, and moves to errors in JSON output. The others stay warnings. A code that is not a warning's is refused with the closest one, so a typo never turns the check off. The codes are in the table below.
Use it where a warning should stop something, such as a scheduled job that fails on overdue deadlines, and keep plain lint on pull requests, so a date passing never blocks unrelated work.
Issue codes#
Each issue has a code:
| Code | Cause | Fix |
|---|---|---|
invalid_type | A property is missing or has the wrong type | Use the type the message names |
invalid_value | A value is not one of the permitted choices | Use one of the listed values |
invalid_union | A value matches none of the allowed shapes | Use one of the shapes the page describes |
unrecognized_keys | An object has properties it does not allow | Remove or rename them |
too_small | A value is below its minimum | Meet the minimum |
too_big | A value is above its maximum | Stay within the maximum |
invalid_format | A string does not match its format | Fix the string |
invalid_key | A key of a collection is invalid | Fix the key at the path |
invalid_element | An item of a collection is invalid | Fix the item at the path |
not_multiple_of | A number is not a multiple of the factor | Use a multiple of it |
custom | A contextual rule failed, such as an unknown reference | Follow the message |
invalid_name | A key breaks the naming rules | Rename it and its references |
test_key_collision | Two spec files share a test key, such as checkout.yml and checkout.spec.yml | Rename one, such as to checkout2.spec.yml |
invalid_attribute_namespace | An attribute definition is nested or its name contains a dot | Move or rename it, or declare an object attribute |
reserved_key | A key is reserved | Choose another key |
feature_variable_key_collision | A feature and a global variable share a key | Rename one of them |
reserved_name | An attribute or property name is inherited by JavaScript objects | Choose another name |
duplicate_tag | A feature lists the same tag twice | Remove the repeated tag |
removed_condition_field | A v3 segments or required field remains | Move it into conditions |
removed_schema_type | A v3 double, date or semver type remains | Use number, or a string with a format |
removed_test_field | A feature spec still uses sticky | Rename it to stickyFeatures |
archived_reference | An active definition or spec references an archived one | Remove the reference, or unarchive the definition |
disallowed_condition | A location uses a kind of condition allowedConditions excludes | Move the condition, or allow its kind |
schema_v2_unsupported | A schema "2" target carries v4 only syntax | Keep it out of the target, or use the v3 shape |
deprecated_reference | A warning about a reference to a deprecated definition | Move to its replacement before it is archived |
mixed_list | A warning about a list mixing strings and numbers | Quote every value, or none |
untyped_condition | A warning about a condition reading a json variable, or inside an object without declared properties | Give the variable a declared shape |
missing_conditions | A selector has no conditions | Add conditions, or "*" to match everything |
missing_required_environment | A definition writes nothing for an environment the project requires | Add entries, or write production: [] |
invalid_metadata | metadata is empty, or it, its owner or a deadline has the wrong shape | Follow the message |
metadata_schema | Metadata does not match the project's metadataSchema | Fix the value, or the schema |
deadline_overdue | A warning about an open deadline whose moment has passed | Act on it and set done, or move by |
deadline_due_today | A warning about an open deadline due today | Act on it and set done |
missing_metadata | A definition requireMetadataIn lists has no metadata | Add metadata |
unportable_regex | A pattern uses syntax outside the portable subset | Rewrite it with portable syntax |
regex_backtracking | A pattern can take exponential time on short input | Make each repetition start or end distinctly |
unknown_evaluation_reason | A test expects a reason no SDK returns | Use one of the listed reasons |
removed_evaluation_field | A test expects a v3 evaluation field | Assert reason: conditions_unmet instead |
circular_dependency | Conditions form a dependency cycle | Break the cycle |
dependency_depth_exceeded | A dependency chain exceeds the runtime limit of 256 | Shorten the chain |
dependency_depth | A warning about a chain deeper than 32 | Shorten the chain |
dependency_validation_failed | A dependency could not be checked | Fix the reference in the message |
dependency_expansion_cost | A warning about a large dependency graph | Review the graph |
mutation_order_changed | A warning from --v3-mutation-order | Check which value you meant |
context_value_mismatch | A warning about context outside an attribute schema | Check the supplied value |
composition_experiment_override | A composed override may change an experiment source value | Change targeting on the source experiment |
composition_nullable_mutation | A mutation can traverse a source that normally returns null | Add a fallback or a guarding requirement |
EntityParseError | A file could not be parsed | Fix the syntax at the line given |
Error | Loading or validation threw an error | Fix what the message names |
error | A mutation comparison failed | Fix the mutation in the message |
The message beside each code says what to change. Parser and plugin failures may use their own error class name as the code. Errors in the command's arguments use the CLI error output instead.
Composition warnings#
These advisory warnings do not reject a definition or change the exit status. Lint checks them after the variable passes schema validation.
composition_experiment_override means a mutation or replacement may change a variation or feature variable from a feature declaring variations, including through nested compositions. The final value can differ from the assignment or value recorded by the source evaluation. Change the original experiment when the change belongs to it, and follow the composition exposure guidance.
composition_nullable_mutation means a mutation may traverse a member whose source can normally return null, such as a prerequisite without a fallback or a feature variable without a disabled fallback. A feature variable without that fallback still warns when its feature has an unconditional 100% rule. Add a source fallback or guard the override with conditions on the same source:
notNullon the whole source, with nopathorpath: []notcontaining exactly oneisNullcheck on the whole source, with nopathorpath: []existsornotNullon a source path, since a path cannot exist inside a null source
Checks inherited from parent overrides also guard children. In an and group, one guarding branch is enough. In an or group, every branch must guard the same source. Checks on a different source and not groups with multiple entries do not establish the guard.
The warning does not cover root replacements or every defensive getter null possibility. Append operations that create a null final property as an array do not warn, but traversing a null ancestor still can. A mutation through null otherwise follows normal missing path behaviour and leaves the value unchanged. A matched variable_override_rule does not prove a value changed, so test the final value. Guards do not narrow generated nullable types.
Deprecated references#
This advisory warning does not reject a definition or change the exit status. It marks each place where an active segment, feature or global variable refers to a deprecated feature, feature variable or global variable:
=> Warning: Deprecated feature "liveChat" is referenced. Remove or replace the reference before the feature is archived. (feature chatFileUpload: conditions.0.feature)A deprecated definition still evaluates, so nothing breaks yet. Once it is archived, the same reference fails lint with archived_reference. Definitions that are deprecated or archived themselves do not get the warning, and specs never do, since a deprecated definition still needs its tests.
Deadline warnings#
These advisory warnings do not change the exit status. Each open deadline in a definition's metadata warns with deadline_overdue once its moment has passed, and with deadline_due_today earlier that day:
=> Warning: The "remove" deadline was due by 2027-03-01T09:00:00Z and is not done. Set `done` once the work is done, or move `by` later. (feature checkout: metadata.deadlines.remove)Lint checks deadlines at the moment it runs. --now=2027-03-02T12:00:00Z checks them as they stand at another moment, so a CI job can look a week ahead. Deadlines that are done, and archived definitions, never warn. To fail on them, add --fail-on=deadline_overdue.
Context warnings#
Lint checks test contexts against every declared attribute type and its constraints, including object paths. It covers feature, segment and variable assertions, expanded matrices, scenarios and child contexts. Unknown context keys are ignored, and values with unexpanded matrix placeholders are skipped.
Mismatches produce context_value_mismatch with the path and received value. Each distinct invalid matrix value gets its own warning. Values longer than 80 characters are shortened in the message, while the JSON lint report retains the full value. They do not change the exit status, so tests can deliberately exercise malformed input. A date only value such as now: '2026-11-27' warns because it lacks a time and timezone. Use a complete timestamp.
Context value "2026-11-27" for "now" is not a valid date. The before and after operators do not match this value. Use YYYY-MM-DDTHH:mm:ss with Z or ±HH:mm.CLI evaluate uses the same checks for supplied context without changing its results. Text output lists warnings. JSON output adds a warnings array of { attribute, message } only when there are warnings. SDKs and test runners do not validate context or emit these warnings. A warning does not guarantee a condition is false: not can invert a failed date comparison.
Large dependency graphs#
Lint warns with dependency_expansion_cost when a connected group of requirements could reach more than 1,000 distinct prerequisite edges. Shared paths are counted once. It is a prompt to review the graph, not a limit: what runs depends on short circuiting, the context and any modules. Review the conditions and test representative contexts.
Condition expressions#
A mistake inside a condition expression is reported at its file, line and column, with a caret under the part it is about and, where one is obvious, a hint. Find mistakes shows one. Its code is one of these:
| Code | Cause | Fix |
|---|---|---|
expression_not_allowed | An expression in a project without the option | Set conditionExpressions, or write a tree |
expression_empty, expression_empty_group | An empty expression or empty parentheses | Write a condition, or "*" for everyone |
expression_value_first, expression_literal_condition | A condition starting with a value, or true, false or null alone | Start with a name, as in country == 'nl' |
expression_missing_operator, expression_missing_value | A name followed by another, or an operator without its value | Compare with an operator and a value |
expression_single_equals, expression_triple_equals, expression_tree_operator, expression_unknown_operator, expression_operator_case, expression_spaced_negative | An operator written another way, such as =, ===, equals, <>, IN or not in | Use its spelling in expressions |
expression_symbol_logic, expression_keyword_case, expression_comma, expression_missing_logic, expression_missing_condition | Conditions joined with symbols such as &&, uppercase words or commas, not joined, or a word without a condition beside it | Join conditions with lowercase and and or |
expression_unclosed_parenthesis, expression_unmatched_parenthesis | Parentheses that do not pair | Close each group you open |
expression_double_quotes, expression_unquoted_value, expression_unterminated_string, expression_string_escape | Text in double quotes, without quotes, unclosed or with an unknown escape | Write text in single quotes |
expression_number, expression_version_number | A number not written as in JSON, or a version written as a number | Write 10 or 2.5, and versions as semver('5.5.0') |
expression_list_required, expression_list_value, expression_list_item, expression_list_separator, expression_trailing_comma, expression_unclosed_list | A list missing where an operator needs one, given where it does not, or malformed | Write a list, such as ['paid', 'enterprise'], after in, notIn, includesAny and notIncludesAny |
expression_text_required, expression_number_comparison | A value of the wrong kind, such as a number after contains or text after > | Quote text, and compare versions with semver(...) |
expression_regex_required, expression_regex_operator, expression_unterminated_regex, expression_empty_regex, expression_regex_flags | A pattern missing after matches, used elsewhere, unclosed, empty or with unknown flags | Write /pattern/flags after matches or notMatches, with flags g, i, m and s |
expression_semver_operator, expression_semver_argument, expression_semver_subject | semver(...) with a word operator, without a quoted version, or as the subject | Write version >= semver('5.5.0') |
expression_unknown_call, expression_read_key, expression_read_close, expression_path | A call other than feature, variable and semver, a key without single quotes, a missing ), or brackets without a quoted key or an index | Write feature('liveChat'), and paths such as ['limits.v2'][0] |
expression_variable_comparison, expression_feature_comparison, expression_variation_comparison, expression_variation_path | A variable or variation read without a comparison, a feature compared other than with == true or == false, or a path after .variation | Compare reads as Require a variable value shows |
expression_comment | A # after a condition on the same line | Put the comment on a line of its own |
expression_too_long, expression_too_deep | Over 10,000 characters, or groups nested over 64 deep | Move parts into segments |
expression_unexpected | A character the language does not use | Remove it, or quote it inside text |
expression_mixed_logic | A warning about and and or mixed without parentheses | Add the parentheses its hint shows |
expression_negation_intent | A warning about not around a comparison with a named negative | Use the negative, or add or with notExists |
expression_semver_text | A warning about == or != on a format: semver attribute | Compare with semver('...') |
The warnings do not change the exit status.

