awsコマンドがSymbol not foundで落ちる時の切り分けと回避

Homebrewで入れたawscliが、コマンドを叩くたびにSymbol not foundで止まるようになりました。原因はawscliではなくHomebrewのPython側にあり、直そうとするより公式のpkg版に入れ替えるほうが早く終わります。

Referenced from と Expected in で壊れている層が決まる

dlopenから始まるエラーは、そのコマンド自体の不具合ではなく共有ライブラリのリンク切れです。読むべきは続く2行で、Referenced from:が「誰がそのシンボルを要求しているか」、Expected in:が「どこに無いか」を示します。

aws: [ERROR]: dlopen(/opt/homebrew/Cellar/python@3.14/3.14.6/Frameworks/Python.framework/Versions/3.14/lib/python3.14/lib-dynload/pyexpat.cpython-314-darwin.so, 0x0002): Symbol not found: _XML_SetAllocTrackerActivationThreshold
  Referenced from: /opt/homebrew/Cellar/python@3.14/.../pyexpat.cpython-314-darwin.so
  Expected in:     /usr/lib/libexpat.1.dylib

要求元はHomebrewのPython 3.14に付いてくるpyexpat、探し先はmacOS標準のlibexpatです。この2行だけで、awscliは通り道でしかないと分かります。Homebrewのビルド済みバイナリが要求するシンボルを、実行しているmacOSのlibexpatが持っていない状態です。

なおExpected in:のパスをlsやnmで追っても空振りします。macOSのシステムライブラリはdyld共有キャッシュに入っていて、/usr/lib/libexpat.1.dylibというファイルは実在しないためです。

コマンドを疑う前に、依存側だけで再現させる

層の見当がついたら、awscliを外して依存側だけで再現するか確かめます。1行で済みます。

$ /opt/homebrew/bin/python3.14 -c "import pyexpat"
ImportError: dlopen(...): Symbol not found: _XML_SetAllocTrackerActivationThreshold

同じ例外が出た時点で、awscliのバージョンや設定を調べる必要は消えます。壊れているのはPythonなので、同じPythonに依存している他のコマンドも同じ理由で落ちます。巻き込まれる範囲はこれで一覧できます。

brew uses --installed python@3.14

–version が通っても直ったことにはならない

この件が紛らわしいのは、壊れたままでもaws --versionだけは成功する点です。

$ aws --version
aws-cli/2.36.19 Python/3.14.6 Darwin/25.0.0 source/arm64

$ aws sts get-caller-identity
aws: [ERROR]: dlopen(...): Symbol not found: _XML_SetAllocTrackerActivationThreshold

XMLを解析する処理に入って初めてpyexpatが読み込まれるためです。sts get-caller-identityもec2 describe-regionsも、ヘルプを出すだけのaws sts helpさえ同じエラーで止まりました。動作確認はバージョン表示ではなく、実際に使うサブコマンドで行います。

Python同梱の公式版に、sudoなしで入れ替える

Homebrew側の修正を待つ手もありますが、作業を止められないならAWS公式のpkg版に移るのが確実です。Pythonを同梱しているので外部のライブラリ事情に左右されません。choices.xmlでインストール先を指定すれば管理者権限も要らず、ホームディレクトリに入ります。

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
  <array>
    <dict>
      <key>choiceAttribute</key><string>customLocation</string>
      <key>attributeSetting</key><string>/Users/<ユーザー名></string>
      <key>choiceIdentifier</key><string>default</string>
    </dict>
  </array>
</plist>

curl -o AWSCLIV2.pkg https://awscli.amazonaws.com/AWSCLIV2.pkg
installer -pkg AWSCLIV2.pkg -target CurrentUserHomeDirectory -applyChoiceChangesXML choices.xml
~/aws-cli/aws --version

入れ替わったかは末尾で判別できます。source/arm64ならHomebrew版、exe/arm64なら公式pkg版です。

aws-cli/2.36.19 Python/3.14.6 Darwin/25.0.0 exe/arm64

公式版も同じPython/3.14.6と表示されているのがこの件の要点で、Python 3.14そのものが悪いわけではなく、Homebrewのビルドが参照するlibexpatが噛み合っていないだけだと確認できます。

ひとつ注意点があります。このpkgは~/aws-cli/を作るだけで、PATHにシンボリックリンクを張りません。Homebrew版を残したままだとwhich -a awsは/opt/homebrew/bin/awsのままで、壊れたほうを呼び続けます。フルパスで呼ぶか、Homebrew版を外してから使います。

検証環境はmacOS 26.0.1（arm64）、awscli 2.36.19、Homebrewのpython@3.14は3.14.6です。