Why am I getting a plantUML syntax error with a statechart in a package?

Question

I try to run the following code on plantuml webserver.

@startuml

package "CI/CD and Monitoring System" {

    state "CI/CD Pipeline" {
        [*] --> Idle
        state Idle {
            --> Running : Start Build
        }
        state Running {
            --> Completed : Build Successful
            --> Failed : Build Failed
        }
        state Completed {
            --> Deployed : Deployment Successful
        }
        state Failed {
            --> RollbackInitiated : Rollback Triggered
        }
        state RollbackInitiated {
            --> Idle : Rollback Completed
        }

        state "Testing" as Testing {
            --> TestingInProgress : Start Testing
        }
        state TestingInProgress {
            --> TestingCompleted : Testing Successful
            --> TestingFailed : Testing Failed
        }
        state TestingCompleted {
            --> Deployment
        }
        state TestingFailed {
            --> RollbackInitiated : Rollback Testing
        }

        state "Deployment" as Deployment {
            --> DeploymentInProgress : Start Deployment
        }
        state DeploymentInProgress {
            --> Deployed : Deployment Successful
            --> DeploymentFailed : Deployment Failed
        }
        state DeploymentFailed {
            --> RollbackInitiated : Rollback Deployment
        }
        state Deployed

        state "Rollback" as Rollback {
            --> Idle : Rollback Completed
        }
    }

    state "Monitoring System" {
        [*] --> Monitoring
        state Monitoring {
            --> AlertTriggered : Anomaly Detected
        }
        state AlertTriggered {
            --> IncidentCreated : Alert Acknowledged
            --> AlertResolved : Incident Resolved
        }
        state IncidentCreated {
            --> IncidentResolved : Issue Addressed
        }
        state AlertResolved {
            --> Monitoring : Issue Resolved
        }
    }

    User --> Monitoring
    Developer --> CI/CD Pipeline
    OperationsTeam --> Monitoring
    QualityAssurance --> CI/CD Pipeline

}

@enduml

I was expecting a state chart/ transition diagram but it constantly throws errors:

I tried using chatgpt for help but it keeps returning the same code I gave it.

Even with a simplified minimal version, I get the same error:

@startuml
package p {
  state s {
  }
}
@enduml

What's wrong with this code ?

Answer 1

The reason is that the PlantUML syntax depends on the kind of diagrams. package is allowed in use case diagrams, class diagrams, component diagrams and even activity diagrams, but not for state diagrams. This is an inconsistency in the grammar, but it's documented (what is not explicitly allowed in a diagram is forbidden).

Using package together with states will cause PlanUML to believe that you want to mix different kind of diagrams, which is not allowed, unless you use the allowmixing directive:

@startuml
allowmixing
package "CI/CD and Monitoring System" {
  state S
  usecase X
  class Z
}
@enduml

You can then have a packaged state diagram like this:

@startuml
allowmixing
package "CI/CD and Monitoring System" {
    state  "CI/CD Pipeline"
    state Running 
    Running    --> Completed : Build Successful
    Running   --> Failed : Build Failed
    state Completed 
    state Failed 
}
@enduml

Unfortunately, the alloxmixing workaround does not work anymore as soon as you use nested states with something between curly braces. This seems to be a bug, as the syntax error for this suggests:

@startuml
allowmixing
package "CI/CD and Monitoring System" {
    state  "CI/CD Pipeline" as s1 {
    }
}
@enduml

Note that using the curly braces for a state that is named with a long name, between double quotes, requires the use of an alias. This has nothing to do with the package and applies to all state charts.

Last but not least, there are a number of syntax errors in your state chart, even if you remove the package: everything between the curly braces is supposed to be nested. In particular, new states defined therein are nested states. And transition therein are internal state transitions between nested states. All state transitions must have source_state --> target_state the notation --> target_state without source state is a real syntax error in your code.

A sample of the necessary transformation (yo'd better then define all the states at the top before all the transitions):

state "CI/CD Pipeline" as s1 {
    [*] --> Idle
    Idle --> Running : Start Build
    state Running 
    Running --> Completed : Build Successful
    Running --> Failed : Build Failed
    state Completed 
    Completed    --> Deployed : Deployment Successful
    state Failed 
    Completed --> RollbackInitiated : Rollback Triggered
    state RollbackInitiated 
    RollbackInitiated  --> Idle : Rollback Completed
}

state "Monitoring System" as s2 {
}

User --> Monitoring
Developer --> s1
OperationsTeam --> Monitoring
QualityAssurance --> s1