Help

• I understand and agree to https://books.ropensci.org/targets/help.html.

Description

Context / motivation

When the targets dependency graph contains a cycle, targets errors with a generic message:

dependency graph contains a cycle. If target x depends on target y, then target y must not depend on target x, either directly or indirectly.

This is correct but not very actionable for large pipelines with many targets. In practice, users then have to manually reconstruct the cycle (often by building the graph themselves and hunting the loop), which is slow and error-prone. An existing cycle short circuits many of the debugging tools available in targets: you cannot run tar_visnetwork(), tar_outdated(), or other helper functions until the cycle is resolved. That makes it a particularly troublesome problem to deal with. I recently hunted down a cycle issue by running debugonce(targets:::tar_assert_target_dag) and using the new igraph function find_cycle() to pin down the problem in a local targets session, but it would be nice if targets just printed out that information for you.

Since targets already represents the dependency graph as an igraph object and uses igraph::is_dag() to validate that it is acyclic, I think it would be a significant usability improvement if the error reported one concrete cycle.

Proposed approach

igraph now exposes find_cycle(), which returns a cycle as both a vertex sequence and an edge sequence. (This is a relatively new feature in igraph.) The idea is:

• Keep the current error text as-is.
• When a cycle exists and igraph::find_cycle() is available, append an “Example cycle” section to the error message showing a representative loop.

This would give immediate, actionable information while keeping the behavior unchanged for older igraph versions.

Example of igraph::find_cycle() output (what users can already compute manually)

Example cycle returned from a subgraph:

Vertices:

• data_input
• intermediate_product
• final_product
• helper_data

Edges:

• helper_data -> data_input
• data_input -> intermediate_product
• intermediate_product -> final_product
• final_product -> helper_data

From a user perspective, the useful output is the vertex path (with closure), e.g.

helper_data -> data_input
data_input -> intermediate_product
intermediate_product -> final_product
final_product -> helper_data

Current code location

The current check is in:

tar_assert_target_dag <- function(x, msg = NULL) {
  if (!inherits(x, "igraph") || !igraph::is_dag(x)) {
    default <- paste(
      "dependency graph contains a cycle.",
      "If target x depends on target y, then",
      "target y must not depend on target x,",
      "either directly or indirectly."
    )
    tar_throw_validate(msg %|||% default)
  }
}

Implementation sketch

This helper appends a cycle report when possible. For long cycles it prints the first 5 and last 5 vertices/links to avoid extremely long error messages.

tar_cycle_report <- function(x, head = 5L, tail = 5L) {
  if (!exists("find_cycle", envir = asNamespace("igraph"), inherits = FALSE)) {
    return(NULL)
  }

  fc <- igraph::find_cycle(x, mode = "out")
  if (!length(fc$vertices)) return(NULL)

  v <- igraph::as_ids(fc$vertices)
  n <- length(v)

  # Full closed path
  if (n <= head + tail + 1L) {
    path <- paste0(c(v, v[[1L]]), collapse = " -> ")
    return(paste0("Example cycle (", n, " vertices):\n", path))
  }

  # Truncated closed path: first `head`, "...", last `tail`, then close to start.
  first <- v[seq_len(head)]
  last <- v[(n - tail + 1L):n]

  path <- paste0(
    paste0(first, collapse = " -> "),
    " -> ... -> ",
    paste0(last, collapse = " -> "),
    " -> ",
    v[[1L]]
  )

  paste0("Example cycle (", n, " vertices, truncated):\n", path)
}

tar_assert_target_dag <- function(x, msg = NULL) {
  if (!inherits(x, "igraph") || !igraph::is_dag(x)) {
    default <- paste(
      "dependency graph contains a cycle.",
      "If target x depends on target y, then",
      "target y must not depend on target x,",
      "either directly or indirectly."
    )

    extra <- NULL
    extra <- tar_cycle_report(x)

    text <- msg %|||% default
    if (!is.null(extra) && nzchar(extra)) {
      text <- paste(text, extra, sep = "\n\n")
    }

    tar_throw_validate(text)
  }
}

Behavior / UX notes

• Only reports one cycle (whatever find_cycle() returns), rather than enumerating all cycles.

Example:

Pipeline

list(
  tar_target(t01, t02 + 1),
  tar_target(t02, t03 + 1),
  tar_target(t03, t04 + 1),
  tar_target(t04, t01 + 1),
  tar_target(x01, x02 + 1),
  tar_target(x02, x03 + 1),
  tar_target(x03, x04 + 1),
  tar_target(x04, x01 + 1)
)

Output

Example cycle (4 vertices):
t04 -> t03 -> t02 -> t01 -> t04

• Keeps output bounded with truncation for large loops.

Example:

Pipeline

list(
  tar_target(t01, t02 + 1),
  tar_target(t02, t03 + 1),
  tar_target(t03, t04 + 1),
  tar_target(t04, t05 + 1),
  tar_target(t05, t06 + 1),
  tar_target(t06, t07 + 1),
  tar_target(t07, t08 + 1),
  tar_target(t08, t09 + 1),
  tar_target(t09, t10 + 1),
  tar_target(t10, t11 + 1),
  tar_target(t11, t12 + 1),
  tar_target(t12, t13 + 1),
  tar_target(t13, t14 + 1),
  tar_target(t14, t15 + 1),
  tar_target(t15, t16 + 1),
  tar_target(t16, t17 + 1),
  tar_target(t17, t18 + 1),
  tar_target(t18, t19 + 1),
  tar_target(t19, t20 + 1),
  tar_target(t20, t01 + 1) # closes the cycle (length 20)
)

Output

Example cycle (20 vertices, truncated):
t18 -> t17 -> t16 -> t15 -> t14 -> ... -> t03 -> t02 -> t01 -> t20 -> t19 -> t18

• If find_cycle() is unavailable (older igraph), behavior remains unchanged (same current message).
• This should reduce time-to-fix substantially for complex pipelines.

Testing ideas

• Add tests that construct a small cyclic igraph and assert the error includes “Example cycle” plus the expected vertex names.
• Guard tests with skip_if_not(exists("find_cycle", envir = asNamespace("igraph"), inherits = FALSE)) so older igraph doesn’t fail CI.
• Ensure the default message remains unchanged when find_cycle() is not available.

If this approach seems acceptable, I can convert this into an issue + PR.