apache/superset · error · AnnotationLayerInvalidError

Annotation layer parameters are invalid.

Error message

Annotation layer parameters are invalid.

What it means

AnnotationLayerInvalidError (422) at the end of AnnotationLayerUpdateCommand.validate(): the layer exists, but validate_update_uniqueness(name, layer_id=self._model_id) found another layer (excluding this one) already using the requested name, so AnnotationLayerNameUniquenessValidationError was collected and re-raised here with it.

Source

Thrown at superset/commands/annotation_layer/update.py:64

        self.validate()
        assert self._model
        return AnnotationLayerDAO.update(self._model, self._properties)

    def validate(self) -> None:
        exceptions: list[ValidationError] = []
        name = self._properties.get("name", "")
        self._model = AnnotationLayerDAO.find_by_id(self._model_id)

        if not self._model:
            raise AnnotationLayerNotFoundError()

        if not AnnotationLayerDAO.validate_update_uniqueness(
            name, layer_id=self._model_id
        ):
            exceptions.append(AnnotationLayerNameUniquenessValidationError())

        if exceptions:
            raise AnnotationLayerInvalidError(exceptions=exceptions)

View on GitHub (pinned to f4587218dd)

Solutions

1. Search for the target name first: GET /api/v1/annotation_layer/?q=(name:eq:<new_name>) and pick a different name if owned by another layer.
2. If merging layers, move annotations to the surviving layer rather than renaming the duplicate.
3. Use the field-level message in _exceptions[0] to surface 'Name must be unique' in the UI.

Example fix

# before
PATCH /api/v1/annotation_layer/12 {"name": "Deploys"}  # layer 3 already named Deploys

# after
PATCH /api/v1/annotation_layer/12 {"name": "Deploys - archived"}

from superset.daos.annotation_layer import AnnotationLayerDAO

new_name = properties["name"]
if not AnnotationLayerDAO.validate_update_uniqueness(new_name, layer_id=model_id):
    return {"error": f"name '{new_name}' already used by another layer"}, 422

try:
    UpdateAnnotationLayerCommand(model_id, {"name": name}).run()
except AnnotationLayerInvalidError as ex:
    # ex._exceptions[0].messages == ['Name must be unique'] on field 'name'
    suggest_alternative_name(name)

When it happens

Trigger: PATCH /api/v1/annotation_layer/<id> renaming to a name owned by a different layer; two layers being swapped/merged by renaming both to the same value.

Common situations: Case-insensitive name collisions (e.g. 'deploys' vs 'Deploys'); merging layers by rename instead of moving annotations.

Related errors

• Annotation parameters are invalid.
• Annotation layer parameters are invalid.
• A semantic view with name '{name}' and the same configuratio
• Annotation parameters are invalid.
• Annotation layer not found.

AI-assisted analysis of apache/superset@f4587218dd (2026-08-14). Data as JSON: /api/errors/966d548ac5f73672. Report an issue: GitHub.