ftplib.error_tempのトラブルシューティング：Python FTPエラーを解決する

2025-06-06

具体的にどのような場合に発生するかというと、例えば以下のような状況が考えられます。

処理の途中でタイムアウトが発生した場合: サーバーがクライアントからの要求に対する処理に時間がかかりすぎ、一時的なエラーとして扱われる場合があります。
ファイルシステムの一時的な問題: サーバー側のディスク容量が一時的に不足している、あるいはファイルのロックなどで操作が一時的に実行できない場合などです。
サーバーが一時的に利用できない場合: サーバーが過負荷状態であったり、メンテナンス中であったりして、一時的に要求を処理できない場合に421 Service not available, closing control connection.のような応答が返ってくることがあります。

ftplib.error_tempは、ftplib.errorのサブクラスです。したがって、例外処理を行う際には、ftplib.errorで捕捉することも可能ですが、より具体的に一時的なエラーを区別して処理したい場合にはftplib.error_tempを捕捉するのが適切です。

一時的なエラーであるため、多くの場合、少し時間を置いてから再度同じ操作を試みることで解決することがあります。そのため、プログラムでこの例外を捕捉した際には、リトライ処理を実装することが一般的な対応策となります。

from ftplib import FTP, error_temp, error_perm, error_proto

try:
    with FTP('ftp.example.com') as ftp:
        ftp.login('user', 'password')
        # 何らかのFTP操作
        ftp.cwd('/public_html')
except error_temp as e:
    print(f"一時的なFTPエラーが発生しました: {e}")
    print("しばらく待ってから再試行してください。")
except error_perm as e:
    print(f"永続的なFTPエラーが発生しました (アクセス権の問題など): {e}")
except error_proto as e:
    print(f"FTPプロトコルエラーが発生しました: {e}")
except Exception as e:
    print(f"その他のエラーが発生しました: {e}")

`ftplib.error_temp`の一般的なエラーシナリオ

- 説明: FTPサーバーが同時に処理できる接続数を超えていたり、リソースが枯渇している場合に発生します。また、サーバーのメンテナンス中や、一時的なクラッシュなどでも起こりえます。
- 表示例: ftplib.error_temp: 421 Service not available, closing control connection.
ファイルシステムの一時的な問題 (例: 450 Requested file action not taken: file unavailable)
- 説明: サーバー側でファイルが一時的にロックされている、他のプロセスが使用中である、あるいはディスク容量が一時的に不足しているなどの場合に発生します。ファイルの書き込みや削除操作でよく見られます。
- 表示例: ftplib.error_temp: 450 Requested file action not taken: file unavailable (e.g., file busy).
データ転送の一時的な問題 (例: 426 Connection closed; transfer aborted.)
- 説明: データ転送中にネットワークの問題（切断、タイムアウト）が発生したり、サーバー側で何らかの理由により転送が中断された場合に発生します。
- 表示例: ftplib.error_temp: 426 Connection closed; transfer aborted.
コマンドの処理が一時的に中断された (4xx系の一般的なエラー)
- 説明: FTPサーバーが特定のコマンド（例: STOR、RETR、DELEなど）を処理している最中に、一時的な障害が発生した場合に起こります。
- 表示例: FTPサーバーの実装によって異なりますが、451 Requested action aborted: local error in processing. など。

ftplib.error_tempは一時的な性質を持つため、最も効果的なトラブルシューティングは「リトライ（再試行）」です。

接続の再確立
- 方法: ftplib.error_tempが発生した場合、現在のFTPセッションが破損している可能性があります。特に421 Service not available, closing control connection.のようなエラーの場合は、既存の接続を切断し、新しく接続を確立し直すことで問題が解決することがあります。
- 考慮点: ftplibのwithステートメントを使用している場合、接続は自動的に閉じられますが、リトライの前に明示的にftp.quit()を呼び出すか、新しいFTPインスタンスを作成して再接続を試みるのが確実です。
待機時間の調整
- 方法: リトライ間の待機時間を長くすることで、サーバーが回復するまで十分な時間を与えることができます。特にサーバーが過負荷状態にある場合や、ネットワークが不安定な場合に有効です。
サーバー側の状態確認
- 方法: もし可能であれば、FTPサーバーの管理者に連絡し、サーバーの稼働状況やリソース使用状況を確認してもらうと良いでしょう。サーバーログを確認してもらうことで、具体的なエラーの原因が判明することもあります。
- 確認点: サーバーのディスク容量、CPU/メモリ使用率、同時接続数制限など。
ネットワークの安定性確認
- 方法: クライアント側（Pythonスクリプトを実行しているマシン）からFTPサーバーへのネットワーク接続が安定しているか確認します。pingコマンドやtracerouteコマンドを使用して、パケットロスや高い遅延がないか確認してください。
ftplibのバージョン確認
- 方法: ごく稀に、ftplibモジュール自体のバグが原因である可能性もゼロではありません。Pythonのバージョンを最新に保つことで、既知のバグが修正されていることがあります。

ftplib.error_perm (5xx系): 永続的なエラー。認証情報の誤り、ファイルやディレクトリの権限不足、存在しないパスへのアクセスなど、リトライしても解決しない問題を示します。これらのエラーが発生した場合は、コードや設定を見直す必要があります。
ftplib.error_temp (4xx系): 一時的なエラー。リトライで解決する可能性があります。

ここでは、ftplib.error_tempの捕捉とリトライ処理の実装例をいくつかご紹介します。

基本的なtry-exceptブロックでの捕捉

これは最も基本的な形で、エラーが発生した際にメッセージを表示するだけの例です。リトライは行いません。

from ftplib import FTP, error_temp, error_perm, error_proto

try:
    with FTP('ftp.example.com') as ftp:
        ftp.login('user', 'password')
        print("FTPサーバーに接続しました。")

        # 例: 存在しないディレクトリに移動しようとして一時エラーが発生する可能性
        # (ただし、多くの場合、永続エラー (550) が返されます。
        #  ここではあくまで error_temp の例として記述します。)
        # 実際には、サーバーが一時的に応答しない場合や、
        # 他の操作で一時エラーが発生するシナリオを想定してください。
        ftp.cwd('/non_existent_temp_error_dir')

        print("FTP操作を完了しました。")

except error_temp as e:
    print(f"一時的なFTPエラーが発生しました: {e}")
    print("このエラーは一時的なものです。しばらく待ってから再試行すると解決するかもしれません。")
except error_perm as e:
    print(f"永続的なFTPエラーが発生しました (例: 認証失敗、アクセス権の問題): {e}")
except error_proto as e:
    print(f"FTPプロトコルエラーが発生しました: {e}")
except Exception as e:
    print(f"予期せぬエラーが発生しました: {e}")
finally:
    print("FTP接続処理を終了します。")

解説:

この例ではリトライは行わず、エラーメッセージを出力するだけです。
except error_temp as e:でftplib.error_tempを捕捉します。捕捉された例外オブジェクトは変数eに格納され、エラーメッセージに利用できます。
tryブロック内でFTP操作を実行します。

ループを使った簡単なリトライ処理

一定回数だけ操作を再試行する、より実践的な例です。

import time
from ftplib import FTP, error_temp, error_perm, error_proto

FTP_HOST = 'ftp.example.com' # 実際にはあなたのFTPサーバーのホスト名に置き換えてください
FTP_USER = 'user'            # あなたのFTPユーザー名に置き換えてください
FTP_PASS = 'password'        # あなたのFTPパスワードに置き換えてください

MAX_RETRIES = 3             # 最大再試行回数
RETRY_DELAY = 5             # 再試行間の待機時間（秒）

def connect_and_list_files():
    ftp = None
    for attempt in range(MAX_RETRIES):
        print(f"接続とファイル一覧取得を試行中... (試行回数: {attempt + 1}/{MAX_RETRIES})")
        try:
            # FTP接続の確立
            ftp = FTP(FTP_HOST)
            ftp.login(FTP_USER, FTP_PASS)
            print("FTPサーバーに接続しました。")

            # ファイル一覧の取得（この操作で一時エラーが発生する可能性を想定）
            file_list = ftp.nlst()
            print("ファイル一覧:")
            for item in file_list:
                print(f"- {item}")
            return True # 成功したらTrueを返して終了

        except error_temp as e:
            print(f"一時的なFTPエラーが発生しました: {e}")
            if attempt < MAX_RETRIES - 1:
                print(f"{RETRY_DELAY}秒待って再試行します...")
                time.sleep(RETRY_DELAY)
            else:
                print("最大再試行回数に達しました。処理を中断します。")
                return False
        except error_perm as e:
            print(f"永続的なFTPエラーが発生しました (例: 認証失敗、アクセス権の問題): {e}")
            return False
        except error_proto as e:
            print(f"FTPプロトコルエラーが発生しました: {e}")
            return False
        except Exception as e:
            print(f"予期せぬエラーが発生しました: {e}")
            return False
        finally:
            if ftp:
                try:
                    ftp.quit() # 接続を閉じる
                    print("FTP接続を閉じました。")
                except Exception as e:
                    print(f"FTP接続終了中にエラーが発生しました: {e}")
    return False

if __name__ == '__main__':
    if connect_and_list_files():
        print("ファイル一覧取得処理が正常に完了しました。")
    else:
        print("ファイル一覧取得処理が最終的に失敗しました。")

解説:

finallyブロックでftp.quit()を呼び出し、接続を確実に閉じます。
最終的に成功しなかった場合はreturn Falseを返します。
成功した場合はreturn Trueで関数を抜けます。
attempt < MAX_RETRIES - 1で、最後の試行の場合は再試行メッセージを出力しないようにしています。
error_tempが発生した場合、time.sleep()で一時停止し、次のループで再試行します。
for attempt in range(MAX_RETRIES):ループを使って、指定回数だけ処理を試みます。
MAX_RETRIESとRETRY_DELAYで、再試行回数と待機時間を設定します。

ftplibの操作が複数の関数に分かれている場合など、共通のリトライロジックを適用したい場合にデコレーターは非常に便利です。

import time
from ftplib import FTP, error_temp, error_perm, error_proto
from functools import wraps

FTP_HOST = 'ftp.example.com'
FTP_USER = 'user'
FTP_PASS = 'password'

def retry_on_temp_error(max_retries=3, delay=5):
    """
    ftplib.error_temp 発生時に指定回数リトライするデコレーター
    """
    def decorator(func):
        @wraps(func)
        def wrapper(*args, **kwargs):
            for attempt in range(max_retries):
                try:
                    return func(*args, **kwargs)
                except error_temp as e:
                    print(f"一時的なFTPエラーが発生しました: {e} (試行 {attempt + 1}/{max_retries})")
                    if attempt < max_retries - 1:
                        print(f"{delay}秒待って再試行します...")
                        time.sleep(delay)
                    else:
                        print("最大再試行回数に達しました。処理を中断します。")
                        raise # 最終的に失敗したら例外を再送出
            return None # ここには到達しないはず
        return wrapper
    return decorator

@retry_on_temp_error(max_retries=5, delay=10)
def connect_ftp():
    ftp = FTP(FTP_HOST)
    ftp.login(FTP_USER, FTP_PASS)
    print("FTPサーバーに接続しました。")
    return ftp

@retry_on_temp_error() # デフォルト値 (max_retries=3, delay=5) を使用
def list_files(ftp_obj):
    print("ファイル一覧を取得中...")
    file_list = ftp_obj.nlst()
    print("ファイル一覧:")
    for item in file_list:
        print(f"- {item}")
    return file_list

@retry_on_temp_error(max_retries=2, delay=3)
def upload_file(ftp_obj, local_path, remote_path):
    print(f"ファイルをアップロード中: {local_path} -> {remote_path}")
    with open(local_path, 'rb') as f:
        ftp_obj.storbinary(f'STOR {remote_path}', f)
    print(f"アップロード完了: {remote_path}")

if __name__ == '__main__':
    ftp_connection = None
    try:
        # FTP接続の試行
        ftp_connection = connect_ftp()

        # ファイル一覧の取得
        if ftp_connection:
            list_files(ftp_connection)

            # ダミーファイルを作成し、アップロードを試行する例
            # 実際には、存在しないパスへのアップロードなどで一時エラーをシミュレート
            try:
                with open("test_upload.txt", "w") as f:
                    f.write("This is a test file for upload.")
                upload_file(ftp_connection, "test_upload.txt", "remote_test_upload.txt")
            except Exception as e:
                print(f"アップロード処理中にエラーが発生しました: {e}")

    except error_perm as e:
        print(f"永続的なFTPエラーが発生しました (最終的な失敗): {e}")
    except error_proto as e:
        print(f"FTPプロトコルエラーが発生しました (最終的な失敗): {e}")
    except Exception as e:
        print(f"予期せぬエラーが発生しました (最終的な失敗): {e}")
    finally:
        if ftp_connection:
            try:
                ftp_connection.quit()
                print("FTP接続を閉じました。")
            except Exception as e:
                print(f"FTP接続終了中にエラーが発生しました: {e}")
        # テスト用ファイルのクリーンアップ
        try:
            import os
            if os.path.exists("test_upload.txt"):
                os.remove("test_upload.txt")
        except Exception as e:
            print(f"テストファイルの削除中にエラーが発生しました: {e}")

解説:

この方法は、コードの重複を減らし、ロジックをよりきれいに保つのに役立ちます。
@retry_on_temp_error()のように関数定義の上にデコレーターを付けることで、その関数にリトライロジックを簡単に適用できます。
raiseステートメントは、最終的にリトライ回数を超えても成功しなかった場合に、例外を呼び出し元に再送出します。これにより、上位のexceptブロックで永続的なエラーとして処理できます。
try-except error_tempブロック内で元の関数を呼び出し、error_tempが発生したらリトライします。
デコレーター内部のwrapper関数が、元の関数（デコレートされた関数）の実行をラップします。
retry_on_temp_errorというデコレーターを定義しています。このデコレーターは、引数として最大リトライ回数と遅延時間を受け取ります。

リトライ処理の代替実装方法

これまでデコレーターを使った例を挙げましたが、それ以外にも様々な方法でリトライロジックを実装できます。

a. 外部ライブラリの利用 (例: `tenacity` / `retrying`)

自前でリトライロジックを実装する代わりに、tenacityやretryingのような専用の外部ライブラリを使用すると、より柔軟で高機能なリトライ処理を簡潔に記述できます。これらは、指数関数的バックオフ、最大試行時間、特定のエラーコードのみのリトライ、エラーフックの実行など、高度な機能を提供します。

tenacityの例

# まずインストールが必要です: pip install tenacity
from ftplib import FTP, error_temp, error_perm, error_proto
from tenacity import retry, stop_after_attempt, wait_fixed, wait_exponential, retry_if_exception_type

FTP_HOST = 'ftp.example.com'
FTP_USER = 'user'
FTP_PASS = 'password'

# @retry デコレーターを使用
# stop_after_attempt: 最大試行回数 (例: 3回)
# wait_fixed: 各試行間の固定待機時間 (例: 5秒)
# wait_exponential: 指数関数的バックオフ (例: 最小0.5秒, 最大10秒の遅延)
# retry_if_exception_type: 指定した例外タイプの場合のみリトライ
@retry(stop=stop_after_attempt(3),
       wait=wait_fixed(5), # または wait=wait_exponential(multiplier=1, min=0.5, max=10),
       retry=retry_if_exception_type(error_temp))
def connect_and_list_files_with_tenacity():
    print("FTP接続とファイル一覧取得を試行中...")
    with FTP(FTP_HOST) as ftp:
        ftp.login(FTP_USER, FTP_PASS)
        print("FTPサーバーに接続しました。")
        file_list = ftp.nlst()
        print("ファイル一覧:")
        for item in file_list:
            print(f"- {item}")
    return True

if __name__ == '__main__':
    try:
        connect_and_list_files_with_tenacity()
        print("ファイル一覧取得処理が正常に完了しました。")
    except error_perm as e:
        print(f"永続的なFTPエラーが発生しました: {e}")
    except error_proto as e:
        print(f"FTPプロトコルエラーが発生しました: {e}")
    except Exception as e:
        print(f"予期せぬエラーが発生しました: {e}")

利点:

特定のエラータイプや条件でのみリトライを行うことができる。
高度なリトライ戦略（指数関数的バックオフ、ジッターなど）を簡単に実装できる。
コードが簡潔になり、可読性が向上する。

b. ステートマシンまたはジェネレーターを使った制御

より複雑なワークフローや、非同期処理を伴うFTP操作の場合、リトライロジックをステートマシンとして設計したり、ジェネレーター関数を使って処理の流れを制御したりする方法も考えられます。これは、エラー発生時に「状態」を保持し、次の試行でその状態から再開するようなケースで有効です。

利点:

非同期処理との連携がしやすい場合がある。
複雑なフローや段階的なリトライ処理をより細かく制御できる。

ftplib.error_tempが示す一時的なエラーに対して、リトライ以外の観点からエラーハンドリングを強化する方法です。

a. ロギングの強化

エラーが発生した際に、単にprint()するだけでなく、標準のloggingモジュールを使用して、詳細なエラー情報をログファイルに出力します。これにより、後から問題の原因を分析しやすくなります。特に本番環境では必須です。

import logging
from ftplib import FTP, error_temp

# ロガーの設定
logging.basicConfig(level=logging.INFO, format='%(asctime)s - %(levelname)s - %(message)s')

def perform_ftp_operation_with_logging():
    try:
        with FTP('ftp.example.com') as ftp:
            ftp.login('user', 'password')
            logging.info("FTPサーバーに接続しました。")
            ftp.cwd('/some/directory') # 一時エラーが発生する可能性のある操作
            logging.info("FTP操作を完了しました。")
    except error_temp as e:
        logging.warning(f"一時的なFTPエラーが発生しました: {e}. 再試行を検討してください。")
    except Exception as e:
        logging.error(f"FTP操作中に予期せぬエラーが発生しました: {e}", exc_info=True) # exc_info=Trueでスタックトレースも出力

if __name__ == '__main__':
    perform_ftp_operation_with_logging()

利点:

本番環境での監視やトラブルシューティングに不可欠。
エラー発生時の状況を詳細に記録できる。

b. 通知システムとの連携

重要なFTP操作でftplib.error_tempが繰り返し発生し、最終的にリトライでも解決しなかった場合など、システム管理者や開発者に自動で通知（メール、Slack、PagerDutyなど）を送る仕組みを導入します。

利点:

システムの安定性向上に寄与する。
問題の早期発見と対応が可能になる。

c. サーキットブレーカーパターン

頻繁に一時エラーが発生する場合、連続して失敗するような状況では、リトライを無闇に行うのではなく、一時的にそのサービス（この場合はFTPサーバー）へのアクセスを停止する「サーキットブレーカー」パターンを適用することも考えられます。これにより、障害が発生しているサービスへの負荷を軽減し、システム全体の回復を早めることができます。

利点:

リソースの無駄な消費を抑える。
障害発生時にシステム全体の障害波及を防ぐ。

d. サーバー側のエラーコードのより詳細な分析

ftplib.error_tempは4xx系の一般的なエラーを示しますが、FTPサーバーはそれぞれ異なる具体的な4xxエラーコード（例: 421, 450, 426など）を返します。これらの具体的なコードを解析し、エラーの種類に応じて異なるリトライ戦略や対処法を適用することも可能です。

from ftplib import FTP, error_temp

try:
    with FTP('ftp.example.com') as ftp:
        ftp.login('user', 'password')
        ftp.storbinary('STOR my_file.txt', open('my_file.txt', 'rb'))
except error_temp as e:
    error_message = str(e)
    if "421" in error_message:
        print("エラーコード 421: サービスが一時的に利用できません。サーバーの過負荷かメンテナンス中かもしれません。")
        # 例: より長い遅延でリトライするか、管理者に通知
    elif "450" in error_message:
        print("エラーコード 450: 要求されたファイル操作ができませんでした (ファイルがロックされている可能性)。")
        # 例: 短い遅延で数回リトライ
    elif "426" in error_message:
        print("エラーコード 426: 接続が閉じられ、転送が中断されました。ネットワークの問題かもしれません。")
        # 例: 接続を再確立してからリトライ
    else:
        print(f"その他の_tempエラー: {error_message}")
except Exception as e:
    print(f"その他のエラー: {e}")

利点:

デバッグ時に具体的な原因を特定しやすくなる。
エラーの種類に応じた、より的確な対処が可能になる。