notarytoolがエラーで終了したときは、終了コードとエラーメッセージから原因を絞り込める。認証エラーでは、使った認証方式によってメッセージが異なる。原因がメッセージだけで分からない場合は、-vを付けて実行すると、Appleのサーバーとの通信の記録が標準エラー出力に表示される。

$ xcrun notarytool history -p "[プロファイル名]" -v

ここでは、終了コードの意味と、認証方式ごとのエラーメッセージ、-vの出力の読み方を紹介する。実行例はXcode 27.0に含まれるnotarytool 1.1.3のもの。

終了コードの意味

notarytoolで確認できた終了コードは、次の5種類である。

終了コード状況
0コマンドが成功した。公証がInvalidになった場合も0になる
1認証や処理に失敗した。Appleのサーバーが認証を拒否した場合(HTTP 401)や、.p8ファイルの内容が不正な場合など
64引数やオプションが不正である
69プロファイルや提出が見つからない
124--timeoutで待機を打ち切った

公証の成否は、終了コードではなく、出力のstatusで判断する。

参考: 【notarytool】提出と待機を分けて公証の完了を待つ (wait)

認証情報を指定していない

認証情報を何も指定しないと、終了コード64で終了する。メッセージには、指定できる認証方式の一覧が表示される。

$ xcrun notarytool history
Error: Must provide credentials.

See the 'store-credentials' command, App Store Connect API arguments for Team Keys (--key, --key-id, --issuer), and Individual Keys (--key, --key-id), or app-specific password arguments (--apple-id, --password, --team-id).
$ echo $?
64

プロファイルが見つからない

-pに存在しないプロファイル名を指定すると、終了コード69で終了する。プロファイル名の打ち間違いか、削除済みのプロファイルを指定している。

$ xcrun notarytool history -p "[存在しないプロファイル名]"
Error: No Keychain password item found for profile: [存在しないプロファイル名]

Run 'notarytool store-credentials' to create another credential profile.
$ echo $?
69

keychainファイルに保存したプロファイルは、--keychainを指定しないと同じエラーになる。

参考: 【notarytool】認証情報の保存先と検証を指定する (store-credentials)

Apple IDとApp用パスワードが誤っている

Apple IDやApp用パスワードが誤っていると、HTTP 401のエラーで終了コード1になる。

$ xcrun notarytool history --apple-id [Apple ID] --team-id [Team ID] --password [誤ったパスワード]
Error: HTTP status code: 401. Invalid credentials. Username or password is incorrect. Use the app-specific password generated at appleid.apple.com. Ensure that all authentication arguments are correct.
$ echo $?
1

メッセージには、Apple IDのパスワードではなく、App用パスワードを使うように書かれている。Apple IDのパスワードを指定していないか、App用パスワードが失効していないかを確認する。

誤りを繰り返すとロックされる場合がある

誤った認証情報で実行を繰り返すと、メッセージが変わった。

$ xcrun notarytool history --apple-id [Apple ID] --team-id [Team ID] --password [誤ったパスワード]
Error: HTTP status code: 401. Your Apple ID has been locked. Visit iForgot to reset your account (https://iforgot.apple.com), then generate a new app-specific password. Ensure that all authentication arguments are correct.

実在しないApple IDに、数回続けて誤ったパスワードを送った場合の結果である。実在するApple IDでも、同様にロックされる可能性がある。認証が失敗したら、同じ認証情報での実行を繰り返さず、原因を確認する。

APIキーの指定が誤っている

APIキーで認証する場合は、指定が誤っている箇所によって、終了コードとメッセージが異なる。

誤り終了コードメッセージ
-kか-dの省略64Must provide all App Store Connect API arguments for Team Keys ...
-kに存在しないファイルを指定64The value '...' is invalid for '-k <key>': The file couldn’t be opened because it doesn’t exist.
-d(Key ID)の誤り1HTTP status code: 401. Unauthenticated. ...
-iがUUIDの形式でない64The value '...' is invalid for '-i <issuer>': ... must be a valid UUID
-i(Issuer ID)の誤り(UUIDの形式は正しい)1HTTP status code: 401. Unauthenticated. ...
.p8ファイルの内容が不正1Error: invalidPEMDocument
-iの省略(Teamキーの場合)1HTTP status code: 401. Unauthenticated. ...

ファイルの指定や、オプションの省略は、引数の検証の段階で終了コード64になる。Appleのサーバーに送った認証情報が誤っている場合は、終了コード1の401エラーになる。

401エラーのメッセージは、Key IDとIssuer IDのどちらが誤っていても同じである。-iを指定しているか、Key IDとIssuer IDの値が正しいかを確認する。

参考: 【notarytool】App Store Connect APIキーで認証する (-k -d -i)

複数の認証方式を指定した場合

APIキーと、Apple ID・App用パスワードを同時に指定した場合は、APIキーで認証できた。Apple IDとパスワードが誤っていても、エラーにならなかった。

$ xcrun notarytool history -k [AuthKey_XXXXXXXXXX.p8のパス] -d [Key ID] -i [Issuer ID] --apple-id [Apple ID] --team-id [Team ID] --password [誤ったパスワード]
Successfully received submission history.
  ...

意図しない認証方式で実行されないよう、認証方式は1つだけ指定する。

-vで通信の記録を確認する

-v(--verbose)を付けると、notarytoolの処理の記録が標準エラー出力に表示される。標準出力には、通常の出力が表示される。

$ xcrun notarytool history -k [AuthKey_XXXXXXXXXX.p8のパス] -d [Key ID] -i [Issuer ID] -v
[時刻] Debug [MAIN] Running notarytool version: 1.1.3 (42), date: [日時], command: [実行したコマンド]
[時刻] Info [API] Initialized Notary API with base URL: https://appstoreconnect.apple.com/notary/v2/
[時刻] Info [API] Preparing GET request to URL: https://appstoreconnect.apple.com/notary/v2/submissions?, ...
[時刻] Debug [JWT] Generating new JWT for key ID: [Key ID].
[時刻] Debug [JWT] JWT Key Type: Team
[時刻] Debug [AUTHENTICATION] Authenticating request with App Store Connect API credentials. Key ID: [Key ID], Issuer ID: [Issuer ID]
[時刻] Debug [API] Received response status code: 200, message: no error, URL: https://appstoreconnect.apple.com/notary/v2/submissions?, Correlation Key: [キー]
...

確認できる項目は、次のとおりである。

  • notarytoolのバージョンと、実行したコマンド
  • 接続先のURL(https://appstoreconnect.apple.com/notary/v2/)
  • APIキーで認証する場合の、JWTのキーの種類(JWT Key Type: Team)と、使われたKey IDとIssuer ID
  • Appleのサーバーが返したHTTPステータスコード

-vを2回指定しても(-vv)、記録の行数は変わらなかった。

401エラーの記録

認証エラーのときは、Received response status code: 401, message: unauthorizedの行が記録される。

$ xcrun notarytool history -k [AuthKey_XXXXXXXXXX.p8のパス] -d [誤ったKey ID] -i [Issuer ID] -v
...
[時刻] Debug [JWT] Generating new JWT for key ID: [誤ったKey ID].
[時刻] Debug [AUTHENTICATION] Authenticating request with App Store Connect API credentials. Key ID: [誤ったKey ID], Issuer ID: [Issuer ID]
[時刻] Debug [API] Received response status code: 401, message: unauthorized, URL: https://appstoreconnect.apple.com/notary/v2/submissions?, Correlation Key: [キー]
[時刻] Error [API] Received non-JSON response body from Notary API, URL: https://appstoreconnect.apple.com/notary/v2/submissions?
...
Error: HTTP status code: 401. Unauthenticated. Ensure that all authentication arguments are correct.

Generating new JWT for key ID:の行で、実際に使われたKey IDを確認できる。シェル変数やCIのSecretsから値を渡している場合、意図した値が渡っているかの確認に使える。

パスワードは伏せられる

--passwordに指定した値は、-vの記録ではprivate<String>と表示され、伏せられる。

$ xcrun notarytool history --apple-id [Apple ID] --team-id [Team ID] --password [パスワード] -v 2>&1 | grep MAIN
[時刻] Debug [MAIN] Running notarytool version: 1.1.3 (42), date: [日時], command: /Applications/Xcode.app/Contents/Developer/usr/bin/notarytool history --apple-id [Apple ID] --team-id [Team ID] --password private<String> -v

ただし、Apple IDやTeam IDは伏せられない。-vの出力をIssueやチャットに貼る場合は、Apple ID、Team ID、Key ID、Issuer IDを確認してから貼る。

公証が成功してもログを確認する

認証に成功しても、公証がInvalidになることがある。失敗した理由は、logで取得するログのissuesに記録される。issuesの各要素には、severity(重大度)、path(対象のファイル)、message(内容)、docUrl(Appleの解説ページ)、architectureなどのキーが含まれる。

$ xcrun notarytool log [提出ID] -p "[プロファイル名]" | jq -c '{status, statusSummary, issues}'
{"status":"Invalid","statusSummary":"Archive contains critical validation errors","issues":[{"severity":"error","code":null,"path":"[アーカイブ名]/[ファイル名]","message":"The binary uses an SDK older than the 10.9 SDK.","docUrl":"https://developer.apple.com/documentation/security/notarizing_macos_software_before_distribution/resolving_common_notarization_issues#3087723","architecture":"arm64"}]}

severityがerrorの問題があると、公証はInvalidになる。Apple公式のTN3147 は、公証が成功した場合も、次回の提出までに直せる警告がログに含まれる場合があるため、常にログを確認するよう書いている。

参考: 【notarytool】公証に失敗した理由をログから調べる