Unity-Technologies/ml-agents · error · TrainerConfigError

When using memory, sequence length must be less than or equa

Error message

When using memory, sequence length must be less than or equal to batch size. 

What it means

When NetworkSettings.memory is enabled (LSTM/memory), the sequence_length must not exceed hyperparameters.batch_size, otherwise batches cannot be formed correctly. attrs validators run at config load time and raise TrainerConfigError.

Source

Thrown at ml-agents/mlagents/trainers/settings.py:655

    time_horizon: int = 64
    summary_freq: int = 50000
    threaded: bool = False
    self_play: Optional[SelfPlaySettings] = None
    behavioral_cloning: Optional[BehavioralCloningSettings] = None

    cattr.register_structure_hook_func(
        lambda t: t == Dict[RewardSignalType, RewardSignalSettings],
        RewardSignalSettings.structure,
    )

    @network_settings.validator
    def _check_batch_size_seq_length(self, attribute, value):
        if self.network_settings.memory is not None:
            if (
                self.network_settings.memory.sequence_length
                > self.hyperparameters.batch_size
            ):
                raise TrainerConfigError(
                    "When using memory, sequence length must be less than or equal to batch size. "
                )

    @checkpoint_interval.validator
    def _set_checkpoint_interval(self, attribute, value):
        if self.even_checkpoints:
            self.checkpoint_interval = int(self.max_steps / self.keep_checkpoints)

    @staticmethod
    def dict_to_trainerdict(d: Dict, t: type) -> "TrainerSettings.DefaultTrainerDict":
        return TrainerSettings.DefaultTrainerDict(
            cattr.structure(d, Dict[str, TrainerSettings])
        )

    @staticmethod
    def structure(d: Mapping, t: type) -> Any:
        """
        Helper method to structure a TrainerSettings class. Meant to be registered with

View on GitHub (pinned to 3ecb446f75)

Solutions

1. Increase hyperparameters.batch_size to be >= network_settings.memory.sequence_length.
2. Lower memory.sequence_length to be <= batch_size.
3. Remove the memory block if recurrent memory is not needed.

Example fix

// before
batch_size: 64
network_settings:
  memory:
    sequence_length: 128
// after
batch_size: 128
network_settings:
  memory:
    sequence_length: 128

if hp and net.get('memory'):
    seq_len = net['memory']['sequence_length']
    if seq_len > hp['batch_size']:
        raise ValueError(f'sequence_length {seq_len} must be <= batch_size {hp["batch_size"]}')

def memory_ok(batch_size, memory):
    return memory is None or memory.get('sequence_length', 0) <= batch_size

from mlagents.trainers.exception import TrainerConfigError
try:
    TrainerSettings.structure(config)
except TrainerConfigError as e:
    if 'sequence length' in str(e).lower():
        config['hyperparameters']['batch_size'] = config['network_settings']['memory']['sequence_length']

When it happens

Trigger: Config sets network_settings.memory.sequence_length greater than hyperparameters.batch_size (e.g. batch_size: 64 with sequence_length: 128).

Common situations: Tuning memory settings for partially observable tasks and increasing sequence_length without touching batch_size; copying sequence_length values from another config with larger batch sizes.

Related errors

• Expected parentIndices[0] to be -1, got {parentIndices[0]}
• The behavior {name} needs a continuous input of dimension {_
• Config file could not be found at {abs_path}.
• There was an error decoding Config file from {config_path}.
• Error parsing yaml file. Please check for formatting errors.

AI-assisted analysis of Unity-Technologies/ml-agents@3ecb446f75 (2026-09-02). Data as JSON: /api/errors/50f0fe3500ba84d9. Report an issue: GitHub.