tensorflow/models · error · ValueError

`global_step` must be a `tf.Variable`.

Error message

`global_step` must be a `tf.Variable`.

What it means

Error "`global_step` must be a `tf.Variable`." thrown in tensorflow/models.

Source

Thrown at orbit/controller.py:206

            "`steps_per_loop` is required when `trainer` is provided.")
      elif not callable(steps_per_loop) and (
          not isinstance(steps_per_loop, int) or steps_per_loop < 1):
        raise ValueError(
            f"`steps_per_loop` ({steps_per_loop}) must be a positive integer "
            "or a callable.")

      if summary_interval is not None:
        if summary_interval <= 0:
          raise ValueError(
              f"`summary_interval` ({summary_interval}) must be larger than 0.")
        elif not callable(steps_per_loop) and (summary_interval % steps_per_loop
                                               != 0):
          raise ValueError(
              f"`summary interval` ({summary_interval}) must be a multiple "
              f"of `steps_per_loop` ({steps_per_loop}).")

    if not isinstance(global_step, tf.Variable):
      raise ValueError("`global_step` must be a `tf.Variable`.")

    self.trainer = trainer
    self.evaluator = evaluator

    self.strategy = strategy or tf.distribute.get_strategy()

    self.train_actions = () if train_actions is None else tuple(train_actions)
    self.eval_actions = () if eval_actions is None else tuple(eval_actions)

    self.global_step = global_step
    self.checkpoint_manager = checkpoint_manager
    self._enable_async_checkpoint_saving = enable_async_checkpointing
    self._checkpoint_options = tf.train.CheckpointOptions(
        enable_async=enable_async_checkpointing
    )

    if self.trainer is not None:
      self.step_timer = None

View on GitHub (pinned to e006f5f0d5)

Solutions

1. Pass global_step as a tf.Variable (e.g. tf.Variable(0, dtype=tf.int64)).
2. Use the optimizer's iterations variable as global_step.

When it happens

Trigger: Thrown at orbit/controller.py:206 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of tensorflow/models@e006f5f0d5 (2026-08-24). Data as JSON: /api/errors/1fdec72159e59eb5. Report an issue: GitHub.