Error: The parallel step can only be used as the only top-level step

Question

When I use this script it works as expected:

stage("B") {
    parallel (
        'C' : { 
            stage ("BC") {
                parallel (
                    'E' : {
                        stage("Many") {
                            println "E1"
                            println "E2"
                        }
                    },
                    'F' : { println "F" }
                )
            }
        },
        'D' : { println "D" }
    )
}

But if enclosed in a pipeline block it fails with an Error "Invalid step 'stage' used - not allowed in this context - The stage step cannot be used in step blocks in Pipeline"

pipeline {
    agent label:"debian"
    stages {
        stage("B") {
            parallel (
                'C' : { 
                    stage ("BC") {
                        parallel (
                            'E' : {
                                stage("Many") {
                                    println "E1"
                                    println "E2"
                                }
                            },
                            'F' : { println "F" }
                        )
                    }
                },
                'D' : { println "D" }
            )
        }
    }
}

Any idea why?

Answer 1

As you can see nested stages cannot contain further parallel stages themselves in declarative pipelines.

I also think it's a bad idea to use parallel in parallel in combination with scripted pipelines because it cannot be displayed correctly in blue ocean.

For example:

import java.text.SimpleDateFormat

node() {
   stage('Build') {
      parallel (
         "win7-vs2012" : { 
            stage("checkout (win7-vs2012)") { 
               println 'checkout Win'
               sleep(20)
               println(new SimpleDateFormat("HH:mm:ss").format(new Date()))
            };
            stage("build (win7-vs2012)") { 
               println 'Build Win'
               sleep(45)
               println(new SimpleDateFormat("HH:mm:ss").format(new Date()))
            }; 
            stage("test (win7-vs2012)") { 
               parallel (
                  "test1 (win7-vs2012)" : {
                     stage("test1 (win7-vs2012)") { 
                        println 'TestRunner 1'
                        sleep(1)
                        println(new SimpleDateFormat("HH:mm:ss").format(new Date()))
                     } 
                  },
                  "test2 (win7-vs2012)" : {
                     stage("test2 (win7-vs2012)") { 
                        println 'TestRunner 2'
                        sleep(1)
                        println(new SimpleDateFormat("HH:mm:ss").format(new Date()))
                     } 
                  },
                  "test3 (win7-vs2012)" : {
                     stage("test3 (win7-vs2012)") { 
                        println 'TestRunner 3'
                        sleep(1)
                        println(new SimpleDateFormat("HH:mm:ss").format(new Date()))
                     } 
                  }
               )
            } 
         },
         "win10-vs2015" : { 
            stage("checkout (win10-vs2015)") { 
               println 'checkout Win'
               sleep(15)
               println(new SimpleDateFormat("HH:mm:ss").format(new Date()))
            };
            stage("build (win10-vs2015)") { 
               println 'Build Win'
               sleep(40)
               println(new SimpleDateFormat("HH:mm:ss").format(new Date()))
            }; 
            stage("test (win10-vs2015)") { 
               parallel (
                  "test1 (win10-vs2015)" : {
                     stage("test1 (win10-vs2015)") { 
                        println 'TestRunner 1'
                        sleep(1)
                        println(new SimpleDateFormat("HH:mm:ss").format(new Date()))
                     } 
                  },
                  "test2 (win10-vs2015)" : {
                     stage("test2 (win10-vs2015)") { 
                        println 'TestRunner 2'
                        sleep(1)
                        println(new SimpleDateFormat("HH:mm:ss").format(new Date()))
                     } 
                  },
                  "test3 (win10-vs2015)" : {
                     stage("test3 (win10-vs2015)") { 
                        println 'TestRunner 3'
                        sleep(1)
                        println(new SimpleDateFormat("HH:mm:ss").format(new Date()))
                     } 
                  }
               )
            } 
         },
         "linux-gcc5" : { 
            stage("checkout (linux-gcc5)") { 
               println 'checkout Win'
               sleep(10)
               println(new SimpleDateFormat("HH:mm:ss").format(new Date()))
            };
            stage("build (linux-gcc5)") { 
               println 'Build Win'
               sleep(20)
               println(new SimpleDateFormat("HH:mm:ss").format(new Date()))
            }; 
            stage("test (linux-gcc5)") { 
               parallel (
                  "test1 (linux-gcc5)" : {
                     stage("test1 (linux-gcc5)") { 
                        println 'TestRunner 1'
                        sleep(2)
                        println(new SimpleDateFormat("HH:mm:ss").format(new Date()))
                     } 
                  },
                  "test2 (linux-gcc5)" : {
                     stage("test2 (linux-gcc5)") { 
                        println 'TestRunner 2'
                        sleep(2)
                        println(new SimpleDateFormat("HH:mm:ss").format(new Date()))
                     } 
                  },
                  "test3 (linux-gcc5)" : {
                     stage("test3 (linux-gcc5)") { 
                        println 'TestRunner 3'
                        sleep(2)
                        println(new SimpleDateFormat("HH:mm:ss").format(new Date()))
                     } 
                  }
               )
            } 
         },
      )
   }
}

Is interpreted as:

But as so often there are good workarounds. I would recommend to trigger a new build in a parallel stage.

pipeline {
   agent none
   stages {
      stage("Example") {
         failFast true
         parallel {
            stage("win7-vs2012") {
               agent {
                  label "win7-vs2012"
               }
               stages {
                  stage("checkout (win7-vs2012)") {
                     steps {
                        echo "win7-vs2012 checkout"
                     }
                  } 

                  stage("build (win7-vs2012)") {
                     steps {
                        echo "win7-vs2012 build"
                     }
                  }

                  stage("test (win7-vs2012)") {
                     steps {
                        build 'test-win7-vs2012'
                     }
                  }
               } 
            }

            stage("win10-vs2015") {
               agent {
                  label "win10-vs2015"
               }
               stages {
                  stage("checkout (win10-vs2015)") {
                     steps {
                        echo "win10-vs2015 checkout"
                     }
                  } 

                  stage("build (win10-vs2015)") {
                     steps {
                        echo "win10-vs2015 build"
                     }
                  }

                  stage("test (win10-vs2015)") {
                     steps {
                        build 'test-win10-vs2015'
                     }
                  }
               } 
            }

            stage("linux-gcc5") {
               agent {
                  label "linux-gcc5"
               }
               stages {
                  stage("checkout (linux-gcc5)") {
                     steps {
                        echo "linux-gcc5 checkout"
                     }
                  } 

                  stage("build (linux-gcc5)") {
                     steps {
                        echo "linux-gcc5 build"
                     }
                  }

                  stage("test (linux-gcc5)") {
                     steps {
                        build 'test-linux-gcc5'
                     }
                  }
               } 
            }
         }
      }
   }
}

Answer 2

As Jenkins docs say, you cannot nest parallel directives:

The nested stages cannot contain further parallel stages themselves, ...