Ruleset Library Troubleshooting

This guide helps you diagnose and resolve common errors when using ruleset libraries and $ref references. Errors can occur when saving a library (library validation) or when saving a ruleset that imports libraries (semantic ruleset validation).

• Error Messages
  • Reference must contain exactly one # symbol
  • Path within library must not be empty
  • Library name must not start with a slash
  • Empty path segments are not allowed
  • Reference value must be a string
  • References in rulesets must include a library name
  • Library is not imported in this ruleset
  • Key not found at path
  • Array index is out of bounds
  • Type mismatch during path traversal
  • Circular reference detected
  • Cannot merge additional keys with non-object reference
  • Cross-library reference in a library
  • Invalid library import path
• Masking produces unexpected results
• Validation fails after adding library references
• Ruleset validation status shows as invalid (Library error)
• Ruleset or library validation status shows as unknown

Error Messages

Reference must contain exactly one # symbol

Problem

Error parsing ruleset library reference "…": References must contain exactly one `#` symbol

The $ref value is missing the # separator between the library name and the path, or contains more than one #.

Solution

Ensure the $ref value has exactly one # separating the library name from the path.

# Incorrect: missing #
$ref: "my_library/masks/phone_mask"

# Incorrect: multiple #
$ref: "my_library#masks#phone_mask"

# Correct
$ref: "my_library#masks/phone_mask"

Path within library must not be empty

Problem

Error parsing ruleset library reference "…": Path within library must not be empty

The $ref value has a # but nothing after it.

Solution

Add a path after the # pointing to the value you want to reference.

# Incorrect: no path after #
$ref: "my_library#"

# Correct
$ref: "my_library#masks/phone_mask"

Library name must not start with a slash

Problem

Error parsing ruleset library reference "…": Library name "/…" must not start with a slash. Use "…" instead

The library name portion of the $ref (before the #) starts with a /.

Solution

Remove the leading slash from the library name. The error message suggests the corrected name.

# Incorrect
$ref: "/my_namespace/my_library#masks/phone_mask"

# Correct
$ref: "my_namespace/my_library#masks/phone_mask"

Empty path segments are not allowed

Problem

Error parsing ruleset library reference "…": Empty path segments are not allowed. Each path segment must be a key or array index

The path portion of the $ref (after the #) contains consecutive slashes.

Solution

Remove the extra slashes so that each path segment is separated by exactly one /.

# Incorrect: consecutive slashes
$ref: "my_library#masks//phone_mask"

# Correct
$ref: "my_library#masks/phone_mask"

Reference value must be a string

Problem

Error parsing ruleset library reference "…": Reference value must be a string, got <type>

The $ref value is not a string. This can happen if the value is a number, boolean, array, or dictionary.

Solution

Ensure the $ref value is a quoted string.

# Incorrect: numeric value
$ref: 123

# Correct
$ref: "my_library#masks/phone_mask"

References in rulesets must include a library name

Problem

Error parsing ruleset library reference "…": References in rulesets must include a library name

A $ref in a ruleset uses the #path syntax (without a library name), which is only valid inside libraries.

Solution

Add the library name before the #. The library must also be listed in the ruleset's imports block.

# Incorrect in a ruleset: no library name
$ref: "#masks/phone_mask"

# Correct in a ruleset
$ref: "my_library#masks/phone_mask"

Note: The #path syntax (without a library name) is valid inside libraries, where it refers to another part of the same library.

Library is not imported in this ruleset

Problem

Error parsing ruleset library reference "…": Library "…" is not imported in this ruleset

The $ref refers to a library that is not declared in the ruleset's imports block.

Solution

Check the imports block

Ensure the library is listed in the ruleset's imports. The import name must exactly match the namespace and name used in the $ref.

version: "1.0"
imports:
  - my_library
tasks:
  - type: mask_table
    table: customers
    key: id
    rules:
      - column: phone
        masks:
          - $ref: "my_library#masks/phone_mask"

Check for typos in the library name

The library name in the $ref must exactly match the import, including namespace. For example, if the library is in namespace sales/2026, the import must be sales/2026/my_library and the $ref must use sales/2026/my_library#….

Key not found at path

Problem

Error parsing ruleset library reference "…": Key "…" not found at path "…"

The path in the $ref points to a key that does not exist in the library.

Solution

Check for typos in the path

Verify that each segment of the path matches a key in the library. Paths are case-sensitive.

Ensure the path starts from the top level

Paths always start from the top level of the library. For example, to reference a mask called phone_mask, the path must be masks/phone_mask, not just phone_mask.

# Incorrect: missing the section prefix
$ref: "my_library#phone_mask"

# Correct
$ref: "my_library#masks/phone_mask"

Array index is out of bounds

Problem

Error parsing ruleset library reference "…": Array index N is out of bounds at "…" (array has M elements)

The path includes an array index that is larger than the array, or a negative index whose absolute value exceeds the array length.

Solution

Check the array in the library and use a valid index. Array indices are zero-based: the first element is /0, the second is /1, and so on. Negative indices count from the end: /-1 is the last element, /-2 is the second-to-last, and so on.

Type mismatch during path traversal

Problem

Error parsing ruleset library reference "…": Encountered array index at "…", but the item at this point is not an array

or:

Error parsing ruleset library reference "…": Encountered object key at "…", but the item at this point is not an object

The path tries to use an array index on something that isn't an array, or a dictionary key on something that isn't a dictionary (e.g. a scalar value or an array).

Solution

Review the library structure and ensure the path matches the actual data types at each level. The error message indicates where in the path the mismatch occurred.

Circular reference detected

Problem

Circular reference detected: encountered "…" again after processing […]

A chain of $ref references within a library forms a cycle, where reference A points to B, B points to C, and so on, eventually pointing back to A.

Solution

Break the cycle by removing or changing one of the references in the chain. The error message lists the chain of references that were being resolved when the cycle was detected.

# This causes a circular reference error:
other:
  value_a:
    $ref: "#other/value_b"
  value_b:
    $ref: "#other/value_a"

Cannot merge additional keys with non-object reference

Problem

Cannot merge additional keys with non-object reference. Reference "…" resolves to a value of type `…`,
but the containing object has additional keys: …

A $ref has additional keys alongside it (which is used to override fields), but the referenced value is not a dictionary — it's a scalar or an array. Field overriding only works when the $ref resolves to a dictionary.

Solution

Remove the extra keys

If the $ref is intended to replace a scalar or array value, remove any other keys from the same dictionary.

Check the reference path

If you intended to reference a dictionary (e.g. a mask definition), check that the path points to the correct location in the library, and that the referenced value is actually a dictionary rather than an array.

Cross-library reference in a library

Problem

Error parsing ruleset library reference "…": Libraries can only contain references to other parts of the same library,
using `#<path>` without a library name

A $ref inside a library includes a library name, but libraries can only reference themselves.

Solution

Use #path syntax (without a library name) to reference other parts of the same library.

# Incorrect inside a library: includes a library name
masks:
  phone_mask:
    type: from_unique_imitate
    retain_prefix_length:
      $ref: "my_library#other/area_code_length"

# Correct inside a library: self-reference with just #
masks:
  phone_mask:
    type: from_unique_imitate
    retain_prefix_length:
      $ref: "#other/area_code_length"

Invalid library import path

Problem

One of the following errors appears when saving a ruleset:

Library import must not start with '/'
Library import must not end with '/'
Library import must not contain consecutive '/' characters
Library import must not contain path traversal segments ("..")

The library name or namespace in the imports block contains invalid characters.

Solution

Ensure the import path does not start or end with /, does not contain //, and does not contain .. path traversal segments.

# Incorrect
imports:
  - /my_namespace/my_library
  - my_namespace/my_library/
  - my_namespace//my_library
  - my_namespace/../my_library

# Correct
imports:
  - my_namespace/my_library

For more details on valid library names and namespaces, see Library Structure — Name and Namespace.

Masking produces unexpected results

Problem

A masking run completes without errors, but the masked data is not what was expected.

Solution

Check the ruleset in the run log

When a masking run uses libraries, DataMasque resolves all $ref references before masking begins. The run log contains the full ruleset YAML for each task. Review it to confirm that each $ref resolved to the value you expected.

Check the reference path and data type

A common cause is referencing the wrong level in the library. For example, referencing masks/phone_mask (a dictionary containing type, parameters, etc.) when you intended to reference masks/phone_mask/retain_prefix_length (a single parameter value), or vice versa.

Check the referenced value is of the intended type for where it's used. Incorrect data types will not always cause validation errors: for example, replacing a value parameter of from_fixed with a dictionary when you intended to reference a string value within that dictionary will not produce an error at reference resolution time. Instead, the database engine will throw an error during masking, or the column values will be replaced by some representation of the dictionary. See the following example.

# Library
other:
  redacted_values:
    name: John Doe
    phone: 555-1234
    ssn: 123-45-6789

# Rule in ruleset
column: name
masks:
  - type: from_fixed
    value:
      $ref: "my_library#other/redacted_values"  # INCORRECT: should be `my_library#other/redacted_values/name`

Check for unintended field overrides

If you have additional keys alongside a $ref (see overriding fields), those keys take priority over the library values. Verify that any overrides are intentional and that there are no conflicting options between the ruleset and the library.

Validation fails after adding library references

Problem

A ruleset that was previously valid fails validation after adding $ref references to libraries, or after modifying a library that the ruleset imports.

Solution

Check the library is valid

The library itself must pass validation before it can be used by rulesets. Check the library's validation status on the libraries page. If the library is invalid, fix the library first.

Check for conflicting options

When a $ref resolves to a dictionary and the ruleset specifies additional keys alongside it, the combined result must be valid. For example, if the library defines a from_unique_imitate mask with skip_letters: true and the ruleset overrides it with the mutually exclusive option skip_digits: true, the ruleset fails validation.

Review the library and ruleset to check for conflicting values.

Check the $ref syntax

Ensure the $ref is correctly placed. A $ref replaces the value it is written in place of, so putting a $ref in the wrong position can produce a structurally invalid ruleset after resolving the references. See the referencing guide for correct usage of $ref with scalars, arrays, and dictionaries.

Ruleset validation status shows as invalid (Library error)

Problem

The following can cause a ruleset to be invalid with a Library validation error:

• Ruleset depends on a library which does not exist.
• Ruleset depends on a library which is invalid.
• Ruleset references a library but does not import that library.
• Ruleset references a non-existent path within a library.
• When references are resolved, the resulting ruleset is not valid (for example, there are mutually exclusive options).

Solution

Library imports

Check the ruleset is importing from the correct library or libraries, and that they are imported at the top of the ruleset.

Make sure the namespaces are correct. For example, if the library phone_library is in namespace marketing, the import must be marketing/phone_library, not simply phone_library.

Missing or invalid library

Check all imported libraries exist and have the namespace you expect. If the error mentions that a dependent library is invalid, review the library to ensure its syntax is correct.

Error in full ruleset

If there is a Library error on the ruleset with some reference to the YAML not being valid, this indicates an issue with the combined ruleset. (If the library YAML was invalid, this would be indicated by the message Imported library … is invalid instead.) Review $ref entries in the ruleset to ensure they are referencing the correct values in the imported library/ies.

Ruleset or library validation status shows as unknown

Problem

After saving a ruleset or library, the validation status shows as "unknown" instead of "valid" or "invalid".

Solution

For very large rulesets and libraries (containing 60KB or more of YAML), validation runs asynchronously in the background and may take some time to complete. The status should update to "valid" or "invalid" once validation finishes.

If the status remains "unknown" for an extended period, check the DataMasque logs for errors from the validation worker process. To trigger revalidation, open and save the ruleset or library.