apache/superset · error · AnnotationLayerInvalidError

Annotation layer parameters are invalid.

Error message

Annotation layer parameters are invalid.

What it means

AnnotationLayerInvalidError (CommandInvalidError, 422) from AnnotationLayerCreateCommand.validate(): the only check is name uniqueness via AnnotationLayerDAO.validate_update_uniqueness(name). If the name is already used by another annotation layer, AnnotationLayerNameUniquenessValidationError ('Name must be unique', field 'name') is collected and this error raised carrying it.

Source

Thrown at superset/commands/annotation_layer/create.py:54

class CreateAnnotationLayerCommand(BaseCommand):
    def __init__(self, data: dict[str, Any]):
        self._properties = data.copy()

    @transaction(on_error=partial(on_error, reraise=AnnotationLayerCreateFailedError))
    def run(self) -> Model:
        self.validate()
        return AnnotationLayerDAO.create(attributes=self._properties)

    def validate(self) -> None:
        exceptions: list[ValidationError] = []

        name = self._properties.get("name", "")

        if not AnnotationLayerDAO.validate_update_uniqueness(name):
            exceptions.append(AnnotationLayerNameUniquenessValidationError())

        if exceptions:
            raise AnnotationLayerInvalidError(exceptions=exceptions)

View on GitHub (pinned to f4587218dd)

Solutions

1. Check GET /api/v1/annotation_layer/?q=(name:eq:<name>) and reuse the existing layer instead of creating.
2. Make seed scripts idempotent: upsert by name (fetch, then update or create).
3. Disable the submit button while the create request is pending to avoid duplicates.

Example fix

# before
CreateAnnotationLayerCommand({"name": "Deploys"}).run()  # runs twice -> 422

# after
from superset.daos.annotation_layer import AnnotationLayerDAO
if not AnnotationLayerDAO.validate_update_uniqueness("Deploys"):
    layer = AnnotationLayerDAO.find_by_name("Deploys")  # reuse
else:
    CreateAnnotationLayerCommand({"name": "Deploys"}).run()

from superset.daos.annotation_layer import AnnotationLayerDAO

if not AnnotationLayerDAO.validate_update_uniqueness(name):
    return {"error": f"layer name '{name}' already exists"}, 422

try:
    CreateAnnotationLayerCommand({"name": name}).run()
except AnnotationLayerInvalidError as ex:
    if any("unique" in str(m) for e in ex._exceptions for m in e.messages):
        return reuse_existing_layer_by_name(name)

When it happens

Trigger: POST /api/v1/annotation_layer/ with a name that already exists (uniqueness is case-insensitive per DAO implementation); double-submit of the create form; re-running a seed script without cleanup.

Common situations: Seeding default layers twice; two admins creating similarly named layers; retry of a timed-out create that actually succeeded server-side.

Related errors

• Annotation layer parameters are invalid.
• Annotation parameters are invalid.
• Annotation parameters are invalid.
• Dashboard parameters are invalid.
• Field is required

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