# Cylc 8 migration - :succeed or :finish?

**URL:** <https://cylc.discourse.group/t/cylc-8-migration-succeed-or-finish/943>\
**Category:** Tips\
**Created:** [April 18, 2024, 3:18pm UTC](https://cylc.discourse.group/t/cylc-8-migration-succeed-or-finish/943 "2024-04-18T15:18:06Z")\
**Posts on this page:** 4\
**Page:** 1

<div class="post-metadata">

**Author:** ![oliver.sanders](https://yyz2.discourse-cdn.com/free1/user_avatar/cylc.discourse.group/oliver.sanders/32/110_2.png) [@oliver.sanders](https://cylc.discourse.group/u/oliver.sanders)\
**Post date:** [April 18, 2024, 3:18pm UTC](https://cylc.discourse.group/t/cylc-8-migration-succeed-or-finish/943/1 "2024-04-18T15:18:06Z")

</div>

## Quick Overview

Sometimes the `:finish`, [qualifier](https://cylc.github.io/cylc-doc/stable/html/glossary.html#term-qualifier) (or its `:finish-all` & `:finish-any` counterparts for families) were used erroneously in Cylc 7 workflows where `:succeed` (or its `:succeed-all` & `:succeed-any` counterparts) would have been more appropriate.

This may cause validation failures when you try to upgrade to Cylc 8, similar to this one like this:

```auto
GraphParseError: Output foo:succeed can't be both required and optional

```

If you encounter errors like this where `:finish` triggers are present, consider whether you want to permit the task to fail and allow the workflow to move on to the next task.

If you don’t, then `:finish` was probably a mistake, switch it for `:succeeded` and the error will go away.

Otherwise have a look at the [graph branching section of the migration guide](https://cylc.github.io/cylc-doc/stable/html/7-to-8/major-changes/suicide-triggers.html) for upgrade advice.

  

## Full Explanation

### `:succeeded` vs `:finished`

In Cylc graphs, if you don’t specify a [qualifier](https://cylc.github.io/cylc-doc/stable/html/glossary.html#term-qualifier), Cylc assumes you mean `:succeed`.

For example this:

```auto
foo => bar

```

Is shorthand for this:

```auto
foo:succeed => bar

```

There is a special qualifier called `:finished` which is shorthand for `:succeed` **or** `:fail`.

For example this:

```auto
foo:finished => bar

```

If equivalent to this:

```auto
foo:succeed | foo:fail => bar # | means "or"

```

The same goes for the `:finished-all` and `:finished-any` qualifiers which can be used with families.

### Misconception

In Cylc 7, `:finished` was sometimes used by mistake in situations where `:succeed` would have been more appropriate. Especially with family triggers (e.g. `FAMILY:finish-all`) where the difference between `:finish-all` and `:succeed-all` might not have been so obvious to the person who wrote the workflow.

### Issues Upgrading `:finish` to Cylc 8

Cylc 8 is smart enough to know that `:succeed` and `:fail` are opposite outcomes, so it doesn’t allow them to both be [required](https://cylc.github.io/cylc-doc/stable/html/glossary.html#term-required-output).

For example this workflow:

```auto
foo:succeed => bar # foo must succeed
foo:failed => baz # foo must fail

```

Will fail validation:

```console
$ cylc validate .
GraphParseError: Opposite outputs foo:succeeded and foo:failed must both be
optional if both are used

```

To fix the error, we put question marks after the outputs:

```auto
foo:succeed? => bar # foo may succeed
foo:failed? => baz # foo may fail

```

Putting a question mark after a task output tells Cylc that it is [optional](https://cylc.github.io/cylc-doc/stable/html/glossary.html#term-optional-output) (i.e. this output may or may not be generated when the task runs).

At Cylc 8 `:finish` is equivalent to `:succeed? | fail?`, so this:

```auto
foo:finish => bar # foo may either succeed or fail

```

Is equivalent to:

```auto
foo:succeed? | foo:failed? => bar # | means "or"

```

Which means that this workflow:

```auto
foo:finish => bar # foo MAY either succeed or fail
foo => baz # foo MUST succeed

```

Will fail validation:

```auto
$ cylc validate .
GraphParseError: Output foo:succeed can't be both required and optional

```

Because one of the `foo:succeed` triggers has a question mark after it and the other doesn’t.

### How To Fix Issues & Upgrade To Cylc 8

If you encounter this situation, there are two possible fixes.

1. If the `:finish` trigger was used by mistake, swap it for `:succeed`.

2. If the `:finish` trigger was used purposefully, add question marks to allow the task to fail.

---

<div class="post-metadata">

**Author:** ![TomC](https://yyz2.discourse-cdn.com/free1/user_avatar/cylc.discourse.group/tomc/32/115_2.png) [@TomC](https://cylc.discourse.group/u/TomC)\
**Post date:** [April 29, 2024, 2:12am UTC](https://cylc.discourse.group/t/cylc-8-migration-succeed-or-finish/943/2 "2024-04-29T02:12:08Z")

</div>

Is this captured in `cylc lint` for example, in case it is used but isn’t causing validation errors?

---

<div class="post-metadata">

**Author:** ![oliver.sanders](https://yyz2.discourse-cdn.com/free1/user_avatar/cylc.discourse.group/oliver.sanders/32/110_2.png) [@oliver.sanders](https://cylc.discourse.group/u/oliver.sanders)\
**Post date:** [April 29, 2024, 8:32am UTC](https://cylc.discourse.group/t/cylc-8-migration-succeed-or-finish/943/3 "2024-04-29T08:32:40Z")

</div>

It is not possible for us to catch this with `cylc lint` as the usage may be purposeful and often is. The issue is cases where `:finished` had been used in error in Cylc 7 workflows. An issue which will come up during Cylc 8 migration as graph validation is now stricter.

---

<div class="post-metadata">

**Author:** ![wxtim](https://yyz2.discourse-cdn.com/free1/user_avatar/cylc.discourse.group/wxtim/32/151_2.png) [@wxtim](https://cylc.discourse.group/u/wxtim)\
**Post date:** [April 30, 2024, 6:14am UTC](https://cylc.discourse.group/t/cylc-8-migration-succeed-or-finish/943/4 "2024-04-30T06:14:50Z")

</div>

This is to cylc lint what “Duplicate” and “Duplicitous” are to a spell checker - both valid, but one of them is very, very, wrong if the other was intended.
