[hugging face] hf auth login すると、Token is valid が出るのに、その後権限エラーになる場合の対処

1. 症状

具体的には以下のようなことで困っていた。

$ hf auth login
? How would you like to log in? Log in with your browser

    Open this URL in your browser:
        https://hf.co/oauth/device

    And enter the code: XXXX-XXXX

    Waiting for authorization....
Token is valid.

# 途中省略

PermissionError: [Errno 13] Permission denied: '/home/ubuntu/.cache/huggingface/stored_tokens'

Token is valid. っていわれているので、認証は通っているはず。でも、手元のマシン上のファイルの権限に問題があるらしく、 PermissionError によって処理が失敗している。

こんな時にどうすべきなのか、について以下に記載する。

(参考) エラー全文を確認する

$ hf auth login
? How would you like to log in? Log in with your browser

    Open this URL in your browser:
        https://hf.co/oauth/device

    And enter the code: XXXX-XXXX

    Waiting for authorization....
Token is valid.
Traceback (most recent call last):
  File "/home/ubuntu/lab/PARC2026_pre/.venv/bin/hf", line 8, in <module>
    sys.exit(main())
  File "/home/ubuntu/lab/PARC2026_pre/.venv/lib/python3.10/site-packages/huggingface_hub/cli/hf.py", line 133, in main
    app()
  File "/home/ubuntu/lab/PARC2026_pre/.venv/lib/python3.10/site-packages/click/core.py", line 1569, in __call__
    return self.main(*args, **kwargs)
  File "/home/ubuntu/lab/PARC2026_pre/.venv/lib/python3.10/site-packages/click/core.py", line 1490, in main
    rv = self.invoke(ctx)
  File "/home/ubuntu/lab/PARC2026_pre/.venv/lib/python3.10/site-packages/huggingface_hub/cli/_cli_utils.py", line 131, in invoke
    return super().invoke(ctx)
  File "/home/ubuntu/lab/PARC2026_pre/.venv/lib/python3.10/site-packages/click/core.py", line 1970, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
  File "/home/ubuntu/lab/PARC2026_pre/.venv/lib/python3.10/site-packages/huggingface_hub/cli/_cli_utils.py", line 131, in invoke
    return super().invoke(ctx)
  File "/home/ubuntu/lab/PARC2026_pre/.venv/lib/python3.10/site-packages/click/core.py", line 1970, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
  File "/home/ubuntu/lab/PARC2026_pre/.venv/lib/python3.10/site-packages/click/core.py", line 1353, in invoke
    return ctx.invoke(self.callback, **ctx.params)
  File "/home/ubuntu/lab/PARC2026_pre/.venv/lib/python3.10/site-packages/click/core.py", line 907, in invoke
    return callback(*args, **kwargs)
  File "/home/ubuntu/lab/PARC2026_pre/.venv/lib/python3.10/site-packages/huggingface_hub/cli/_framework.py", line 365, in handler
    return func(**call_kwargs)
  File "/home/ubuntu/lab/PARC2026_pre/.venv/lib/python3.10/site-packages/huggingface_hub/cli/auth.py", line 65, in auth_login
    login(token=token, add_to_git_credential=add_to_git_credential, skip_if_logged_in=not force)
  File "/home/ubuntu/lab/PARC2026_pre/.venv/lib/python3.10/site-packages/huggingface_hub/_login.py", line 117, in login
    interpreter_login(skip_if_logged_in=skip_if_logged_in)
  File "/home/ubuntu/lab/PARC2026_pre/.venv/lib/python3.10/site-packages/huggingface_hub/_login.py", line 309, in interpreter_login
    _device_code_login()
  File "/home/ubuntu/lab/PARC2026_pre/.venv/lib/python3.10/site-packages/huggingface_hub/_login.py", line 251, in _device_code_login
    _save_oauth_token(response)
  File "/home/ubuntu/lab/PARC2026_pre/.venv/lib/python3.10/site-packages/huggingface_hub/_login.py", line 257, in _save_oauth_token
    token_name, username = _validate_and_save_token(
  File "/home/ubuntu/lab/PARC2026_pre/.venv/lib/python3.10/site-packages/huggingface_hub/_login.py", line 441, in _validate_and_save_token
    _save_token(token=token, token_name=token_name, refresh_token=refresh_token, expires_at=expires_at)
  File "/home/ubuntu/lab/PARC2026_pre/.venv/lib/python3.10/site-packages/huggingface_hub/utils/_auth.py", line 445, in _save_token
    _save_stored_tokens_full(stored_tokens)
  File "/home/ubuntu/lab/PARC2026_pre/.venv/lib/python3.10/site-packages/huggingface_hub/utils/_auth.py", line 399, in _save_stored_tokens_full
    _write_secret(Path(constants.HF_STORED_TOKENS_PATH), buf.getvalue())
  File "/home/ubuntu/lab/PARC2026_pre/.venv/lib/python3.10/site-packages/huggingface_hub/utils/_auth.py", line 40, in _write_secret
    fd = os.open(str(path), os.O_WRONLY | os.O_CREAT | os.O_TRUNC, _SECRET_FILE_MODE)
PermissionError: [Errno 13] Permission denied: '/home/ubuntu/.cache/huggingface/stored_tokens'

1-1. 発生した環境

Item	Version など	備考
OS	Ubuntu
hf	1.27.0	pip にて install している

2. 対処法

以下を実行する

sudo chown -R $(whoami):$(whoami) /home/ubuntu/.cache/huggingface

中身を消すわけではなく所有者を戻すだけ。既にダウンロード済みのモデル/データセットのキャッシュ(hub や datasets 配下)はそのまま使える。

うまくできたか確認するには、さらに以下のコマンドを実する。

ls -la /home/ubuntu/.cache/huggingface   # ubuntu:ubuntu になっていることを確認
hf auth login
hf auth whoami  # 結果として、hugging face のアカウント名が表示されれば OK

これで OK。
背景や原因など詳しく知りたい方は続きも参照されたし(*˘︶˘*).｡.:*

3. 原因

/home/ubuntu/.cache/huggingface ディレクトリ自体が root 所有になっていることが原因。以下のような感じ。

drwxr-xr-x root root

なぜ /home/ubuntu/.cache/huggingface が root 所有になったのか。

それは、以下のような流れで発生したと考えられる。

1. 過去の docker run 実行時に、このディレクトリをコンテナへマウントしていた
2. その最中にコンテナ内のプロセスが root 権限で動いていた
3. その root ユーザが、書き込んだファイル / ディレクトリ (/home/ubuntu/.cache/huggingface) の所有者が root のまま残ってしまった

その結果として、 docker container の外のホストマシン側ユーザーには書き込み権限が無い状態になった。これでは、 hf auth login を実行しても、新規ファイル stored_tokens を作れずにエラーになる。

4. 再発防止策

今後 docker run する際は、コンテナ側を自分の UID / GID で動かすと同じ問題を避けられる。 root ではなく、ホスト側のユーザでディレクトリを作ってしまえば良い。

# ホストマシンの HuggingFace のキャッシュを、
# docker コンテナ内の `/root/.cache/huggingface` と共有して docker run を実行する

docker run --gpus all --rm -it \
    --user "$(id -u):$(id -g)" \
    -v "$HOME/.cache/huggingface:/root/.cache/huggingface" \
    <image名>

ただし --user を付けると、コンテナ側の HF_HOME=/root/.cache/huggingface（rootのホーム）に一般ユーザーで書き込むことになり権限で落ちる可能性があります。

その場合は Dockerfile の環境変数 HF_HOME=/root/.cache/huggingfaceを /home/ubuntu/.cache/huggingface 相当の中立なパス(例: /hf_home)に変えてから同じパスをマウントする方が確実

とりあえず目の前の chown だけ直せば hf は正常に動くが、 docker コンテナ側で問題が発生する可能性があるので、再発防止策は少し丁寧に検討する必要がある。