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の省略 | 64 | Must provide all App Store Connect API arguments for Team Keys ... |
-kに存在しないファイルを指定 | 64 | The value '...' is invalid for '-k <key>': The file couldn’t be opened because it doesn’t exist. |
-d(Key ID)の誤り | 1 | HTTP status code: 401. Unauthenticated. ... |
-iがUUIDの形式でない | 64 | The value '...' is invalid for '-i <issuer>': ... must be a valid UUID |
-i(Issuer ID)の誤り(UUIDの形式は正しい) | 1 | HTTP status code: 401. Unauthenticated. ... |
.p8ファイルの内容が不正 | 1 | Error: invalidPEMDocument |
-iの省略(Teamキーの場合) | 1 | HTTP 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】公証に失敗した理由をログから調べる
