python-telegram-bot/python-telegram-bot · critical · TypeError

File {filepath.name} does not contain valid pickle data

Error message

File {filepath.name} does not contain valid pickle data

What it means

PicklePersistence with separate files (single_file=False) loads each section file (conversations, user_data, ...) via _load_file. If a section file exists but contains data that pickle rejects (UnpicklingError), TypeError with the file name is raised on first access to that data.

Source

Thrown at src/telegram/ext/_picklepersistence.py:276

            self.user_data = {}
            self.chat_data = {}
            self.bot_data = self.context_types.bot_data()
            self.callback_data = None
        except pickle.UnpicklingError as exc:
            filename = self.filepath.name
            raise TypeError(f"File {filename} does not contain valid pickle data") from exc
        except Exception as exc:
            raise TypeError(f"Something went wrong unpickling {self.filepath.name}") from exc

    def _load_file(self, filepath: Path) -> Any:
        try:
            with filepath.open("rb") as file:
                return _BotUnpickler(self.bot, file).load()

        except OSError:
            return None
        except pickle.UnpicklingError as exc:
            raise TypeError(f"File {filepath.name} does not contain valid pickle data") from exc
        except Exception as exc:
            raise TypeError(f"Something went wrong unpickling {filepath.name}") from exc

    def _dump_singlefile(self) -> None:
        data = {
            "conversations": self.conversations,
            "user_data": self.user_data,
            "chat_data": self.chat_data,
            "bot_data": self.bot_data,
            "callback_data": self.callback_data,
        }
        with self.filepath.open("wb") as file:
            _BotPickler(self.bot, file, protocol=pickle.HIGHEST_PROTOCOL).dump(data)

    def _dump_file(self, filepath: Path, data: object) -> None:
        with filepath.open("wb") as file:
            _BotPickler(self.bot, file, protocol=pickle.HIGHEST_PROTOCOL).dump(data)

View on GitHub (pinned to d3b69d2e9f)

Solutions

1. Identify the offending section from the file name in the message and delete/rename just that file to rebuild only that section
2. Restore the section file from backup
3. Use atomic writes (PicklePersistence's update_interval plus flush) or a custom Persistence writing via os.replace

Example fix

# before
persistence = PicklePersistence(filepath='mydata', single_file=False)
# mydata_conversations corrupt -> TypeError on get_conversations

# after
import os
os.rename('mydata_conversations', 'mydata_conversations.bak')
persistence = PicklePersistence(filepath='mydata', single_file=False)

def check_section_files(base):
    import glob
    for f in glob.glob(base + '_*'):
        try:
            with open(f, 'rb') as fh:
                pickle.load(fh)
        except Exception:
            os.rename(f, f + '.corrupt')

try:
    persistence.get_conversations()
except TypeError as exc:
    name = str(exc).split("'")[0]  # parse file name from message
    os.rename(name.strip(), name.strip() + '.corrupt')

When it happens

Trigger: PicklePersistence(filepath='mydata', single_file=False) with e.g. mydata_conversations present but not valid pickle — corrupted, truncated, or written by a different serializer.

Common situations: Same corruption scenarios as the single-file variant but per-section: one section file (often the largest, conversations) got truncated during a crash, or the directory was partially synced/copied.

Related errors

• File {filename} does not contain valid pickle data
• Something went wrong unpickling {self.filepath.name}
• Something went wrong unpickling {filepath.name}
• callback_data_json is not in the required format
• Unable to deserialize conversations_json. Not valid JSON

AI-assisted analysis of python-telegram-bot/python-telegram-bot@d3b69d2e9f (2026-08-28). Data as JSON: /api/errors/620af847fdfec50e. Report an issue: GitHub.