freqtrade/freqtrade · error · OperationalException

Found non defined labels: {non_defined_labels}, expecting la

Error message

Found non defined labels: {non_defined_labels}, expecting labels: {class_names}

What it means

Before encoding labels to integers, assert_valid_class_names computes the set difference between the values actually present in the target column and the declared class_names. Any label value not in class_names causes an OperationalException (note: the raise passes two strings, so Python joins them into a tuple message). It guards the index mapping self.class_name_to_index[x] from KeyError later.

Source

Thrown at freqtrade/freqai/base_models/BasePyTorchClassifier.py:125

        """
        encode class name, str -> int
        assuming first column of *_labels data frame to be the target column
        containing the class names
        """

        target_column_name = dk.label_list[0]
        for split in self.splits:
            label_df = data_dictionary[f"{split}_labels"]
            self.assert_valid_class_names(label_df[target_column_name], class_names)
            label_df[target_column_name] = [
                self.class_name_to_index[x] for x in label_df[target_column_name]
            ]

    @staticmethod
    def assert_valid_class_names(target_column: pd.Series, class_names: list[str]):
        non_defined_labels = set(target_column) - set(class_names)
        if len(non_defined_labels) != 0:
            raise OperationalException(
                f"Found non defined labels: {non_defined_labels}, ",
                f"expecting labels: {class_names}",
            )

    def decode_class_names(self, class_ints: torch.Tensor) -> list[str]:
        """
        decode class name, int -> str
        """

        return [self.index_to_class_name[x.item()] for x in class_ints]

    def init_class_names_to_index_mapping(self, class_names):
        self.class_name_to_index = {s: i for i, s in enumerate(class_names)}
        self.index_to_class_name = {i: s for i, s in enumerate(class_names)}
        logger.info(f"encoded class name to index: {self.class_name_to_index}")

    def convert_label_column_to_int(
        self,

View on GitHub (pinned to 1c8edfe4d1)

Solutions

1. Make class_names cover every value the target column can take (e.g. ['down', 'neutral', 'up'] if the strategy can emit a neutral class).
2. Ensure target dtype matches class_names exactly (all strings or all ints, no mixed 0/1 with 'down'/'up').
3. Drop or fill NaN target rows in set_freqai_targets so no NaN reaches the classifier.
4. Re-train after the fix; the check runs at training time, so prediction-time surprises are prevented.

Example fix

# before
class_names = ['down', 'up']
dataframe['&-action'] = np.where(dataframe['ret'] < -0.01, 'down',
                        np.where(dataframe['ret'] > 0.01, 'up', 'neutral'))  # 'neutral' undeclared

# after
class_names = ['down', 'neutral', 'up']
self.freqai.class_names = class_names

non_defined = set(df[target].dropna().unique()) - set(class_names)
assert not non_defined, f"Labels {non_defined} not in declared class_names {class_names}"

def labels_within_classes(target: 'pd.Series', class_names: list) -> bool:
    return set(target.dropna().unique()).issubset(set(class_names))

When it happens

Trigger: convert_label_column_to_int -> encode_class_names -> assert_valid_class_names finds a training label the user did not declare, e.g. class_names = ['down', 'up'] but the target column also contains 0 or 'neutral', or targets are numeric while class_names are strings, or NaNs survive into the label column.

Common situations: Target engineering produces a third state (e.g. flat/neutral) the config class_names omits; mixing int targets with str class names; renaming label values in feature engineering without updating class_names; NaN labels from insufficient lookahead.

Related errors

• Class labels must be unique across targets: {self.classes_}
• Missing class names. self.model.model_meta_data['class_names
• self.class_names is empty, set self.freqai.class_names = ['c
• y must have at least two dimensions for multi-output regress
• y must have at least two dimensions for multi-output regress

AI-assisted analysis of freqtrade/freqtrade@1c8edfe4d1 (2026-08-15). Data as JSON: /api/errors/9ab5ff393a51a2ec. Report an issue: GitHub.