トラブルシューティング
APIが起動しない
APIは、設定に問題があると、足りない設定や形式の違う設定の名前だけを表示して止まります。値は表示しません。
Invalid configuration: OIDC_RECHECK_SECONDS
MMT_SESSION_ENCRYPTION_KEY is required when AUTH_MODE=hybrid| 表示 | 直し方 |
|---|---|
MMT_DATABASE_URL is required | .envにDBの接続URLを入れる |
OIDC_ISSUER_URL and OIDC_CLIENT_ID are required when AUTH_MODE=... | Authentikの設定を入れるか、AUTH_MODE=localにする |
MMT_SESSION_ENCRYPTION_KEY is required ...、... must be base64 of 32 bytes | openssl rand -base64 32で作った値を入れる |
OIDC issuer requires HTTPS ... | IssuerをHTTPSのURLにする |
Production URLs require HTTPS | NODE_ENV=productionではMMT_PUBLIC_URLとMMT_WEB_ORIGINをHTTPSにする |
Development authentication is forbidden in production | 本番ではAUTH_MODEをlocal、oidc、hybridのどれかにする |
AUTH_SESSION_IDLE_SECONDS must not exceed AUTH_SESSION_ABSOLUTE_SECONDS | idleをabsolute以下にする |
MMT_GIT_SSH_KEY_PATH and MMT_GIT_KNOWN_HOSTS_PATH must be set together | 両方を設定するか、両方を消す |
OIDC_ALLOWED_GROUPSが空のとき、OIDC_ROLE_MAPPING_JSONにadmin・user以外のroleを書いたときも起動しません。SMTPの設定は、MMT_SMTP_URLとMMT_SMTP_FROMの片方だけでは起動しません。
更新したあとに起動しない場合は、新しく必須になった設定が無いかを確かめてください。SSOの再確認を含むバージョンからはMMT_SESSION_ENCRYPTION_KEYが、groupで許可を決めるバージョンからはOIDC_ALLOWED_GROUPSが必須です。
SSOでログインできない
利用者には理由を区別せずに401を返します。理由は監査ログの「SSOログインの拒否」（auth.oidc.denied）のdetails.reasonと、APIの標準エラー出力の1行のJSON（{"event":"oidc_login_denied","reason":...}）に残ります。全体管理者は、ブラウザでログインした状態で次のURLを開くと確認できます。
https://tracking.example.com/api/audit-events?action=auth.oidc.deniedreason | 意味 | 直し方 |
|---|---|---|
group_not_allowed | OIDC_ALLOWED_GROUPSのどのgroupにも入っていない | Authentikでgroupに入れる。ID tokenにgroupsが出ているかも確かめる |
email_not_verified | emailが無いか、email_verifiedがtrueでない | Authentikでメールアドレスを検証済みにし、scope mappingでemail_verifiedを出す |
user_disabled | このアプリでユーザーが無効になっている | 全体管理者が「全体管理」→［ユーザー］で有効化する |
last_admin | 同期すると有効な全体管理者が0人になる | 別の全体管理者（ローカルの管理者でもよい）を先に用意する |
privileged_link_required | 同じメールアドレスの特権を持つローカルアカウントがある | 自動では結び付けない。全体管理者がローカルアカウントの権限を確かめて対応する |
service_account | Service Accountとしてログインしようとした | Service Accountはログインできない |
監査ログにauth.loginの失敗（details.reasonがinvalid_oidc_state）がある場合や、標準エラー出力にoidc_authentication_failedがある場合は、Authentikとの通信、ログイン画面を開いてから時間がたちすぎた、別のブラウザでcallbackを開いた、などが原因です。もう一度ログインからやり直してください。それでも失敗する場合は、AuthentikのRedirect URIが<MMT_PUBLIC_URL>/api/auth/callbackと完全に一致しているかを確かめます。
ログイン中に急にログイン画面に戻る
SSOのsessionの再確認で、sessionが終了した可能性があります。監査ログの「SSO sessionの再確認による失効」（auth.oidc.recheck）のreasonを確かめます。
reason | 意味 | 直し方 |
|---|---|---|
group_not_allowed | 許可されたgroupから外れた | groupの所属を確かめる。UserInfoにgroupsが出ていないと全員がこれになる |
idp_session_revoked | Authentikがtokenを拒否した（Authentikでログアウトした、など） | もう一度ログインする |
reauthentication_required | refresh tokenが無いままaccess tokenが切れた | OIDC_SCOPESとProviderにoffline_accessを入れる |
「Authentikに接続できない」（503 oidc_unavailable）
API serverからAuthentikに接続できないため、SSOのsessionの権限を確かめられない状態です。sessionは残っているので、Authentikが復旧すれば同じsessionで続けられます。API serverからAuthentikのIssuerのURLへ接続できるかを確かめてください。
Authentikが長く止まる場合は、AUTH_MODE=hybridにしてローカルの管理者でログインできます。
Authentikに接続できないあいだは、前回の確認からOIDC_RECHECK_SECONDSを過ぎたSSOのsessionでは、ログアウトの操作も503になります。ログアウトできなくても、操作は受け付けられません。Authentikが復旧するか、sessionの期限が切れるのを待ってください。
「パスワードを変更」の画面から進めない
初期管理者や、管理者がパスワードを再設定したアカウントは、パスワードを変更するまでほかの画面を使えません（403 password_change_required）。12〜1024 byteで、現在と異なるパスワードに変更してください。
管理者のパスワードが分からなくなった場合は、API serverのターミナルでnpm run bootstrap-admin -w @mmt/apiを実行して再設定します。
「試行回数の上限に達しました」
ログインの試行回数の上限を超えました（429 rate_limited）。応答のRetry-After秒のあいだ待ってから、もう一度試してください。上限は認証方式とローカルアカウントの「パスワード」にあります。
API tokenが401・403になる
| 応答 | 原因 | 直し方 |
|---|---|---|
401 invalid_token | tokenが無効、失効、期限切れ。所有者のユーザーかService Accountが無効 | 新しいtokenを発行する。Service Accountの状態を確かめる |
401 identity_sync_required | SSOのユーザーが7日以上ブラウザでログインしていない | ブラウザで一度ログインすれば、同じtokenが使える。長く動く処理はService Accountのtokenにする |
403 insufficient_scope | tokenのscopeが足りない | 必要なscopeでtokenを発行し直す |
403 project_forbidden | 所有者のProjectのRoleが足りない、またはtokenを限定したProjectと違う | Roleを確かめる。groupから外れていないかも確かめる |
403 session_required | ブラウザでだけ使える操作（自分のパスワード変更、コンピュータの自分の設定、Projectの完全な削除など） | 画面から操作する |
403 job_token_forbidden | Job限定tokenで許されていない操作 | 実行コードから行える操作か確かめる（API tokenとService Account） |
401 basic_auth_unsupported | 独自APIにBasic認証を使った | Bearer tokenにする。Basic認証はMLflow互換APIだけ |
tokenのscopeと限定したProjectは、次のコマンドで確かめられます。
curl -sS -H "Authorization: Bearer $MMT_API_TOKEN" "$MMT_API_URL/api/auth/token"ブラウザの操作が403 invalid_originになる
画面を開いたURLが、許可したoriginと違います。LANやVPNのIPアドレスで開く場合はMMT_ALLOW_PRIVATE_ORIGINS=trueを、DNS名で開く場合はMMT_WEB_ORIGINとMMT_PUBLIC_URLにそのURLを設定して、APIを再起動します。
Projectの権限を変えられない（409）
「Project adminがいなくなるため変更できません。」と表示される場合は、最後のAdminを外そうとしています。先に別のメンバーか、誰かがログインしたことのあるgroupへAdminを付けてください。まだ誰もログインしていないgroupのAdminは数えません（「Authentik group」の一覧に「まだ誰もログインしていません」と出ます）。全体管理者を無効化・降格しようとして409 last_global_adminになる場合も、先に別の全体管理者を用意します。
「このプロジェクトはアーカイブされています」と出る
そのProjectは、ProjectのAdminか全体管理者がアーカイブしました（404 project_archived）。データは残っています。使うときは、全体管理者に「全体管理」→［プロジェクト］の「アーカイブ済みも表示」から［元に戻す］を依頼します（Projectの作成と管理）。
通知が届かない
- ［プロジェクト設定］の「通知」の通知先で、［送信設定］が「設定済み」かを確かめます。「未設定」なら、API serverの
.envに環境変数が無いか、APIを再起動していません。 - ［テスト送信］で、その場で送れるかを確かめます。
- 「直近の送信履歴」で、状態と失敗の理由を確かめます。理由ごとの確認項目は通知と運用アラートの「送信の流れと失敗したとき」にあります。
- 通知ルールが有効で、イベントと条件が合っているかを確かめます。workerの停止とPlugin送信の滞留は、実行種別や実験の条件を付けたルールには届きません。
Mado連携につながらない・送信が滞る
Mado連携の状態は、Projectの［連携］で確かめます。接続設定とキーを直せるのは全体管理者です（Mado連携）。
| 表示 | 直し方 |
|---|---|
「連携キーを保存・利用するには、APIサーバーにMMT_PLUGIN_SECRET_KEYの設定が必要です。」、またはplugin_secret_key_unavailable | API serverの.envにMMT_PLUGIN_SECRET_KEYを設定し、APIを再起動する（環境変数） |
「Madoのアクセストークンを設定してください。」、またはplugin_token_unavailable・plugin_secret_decryption_failed | 「アクセストークン」が「未設定」なら、［Madoの接続設定］でアクセストークンを入れて［保存］を押す。以前の版で用途別のキーを保存した接続も「未設定」になるので、同じく入れ直す。「設定済み」なのに出るなら、MMT_PLUGIN_SECRET_KEYがトークンを保存したときと同じ値かを確かめる。元の値に戻せないときは、アクセストークンを入れ直して保存する |
［接続を確認］で「Madoのアクセストークンに…を許可してください」（plugin_token_scope_missing）、または「RunのNamespace「…」をMadoのアクセストークンで許可してください」（plugin_job_namespace_not_allowed） | MadoのSettings → Access → Access Tokensで、そのトークンにDataLineageの読み取りと送信、「RunのNamespace」を許可してから、もう一度［接続を確認］を押す |
［接続を確認］で「このMadoはアクセストークンの許可範囲の取得（/api/mado/access-token）に対応していません」（plugin_mado_access_token_unsupported） | Madoを、アクセストークン自身の許可範囲を返す版へ更新する |
［接続を確認］で「Madoとの通信に失敗しました」（plugin_request_failed） | API serverから「Mado API URL」に届くか、アクセストークンが有効（無効化・期限切れでない）かを確かめる。容量の読み取りを許可しているなら、容量も取得できるかを確かめる（確認では容量も取得する） |
| 運用アラート「Plugin送信の滞留」 | ［連携］の「イベントの送信状況」で「最終エラー」を確かめ、Madoの状態や接続設定（「OpenLineage URL」、アクセストークン）を直してから［イベントを再送］を押す |
workerがJobを受け取らない・停止と表示される
workerのホストで次を実行します。
mado-tracking-worker status --worker-id gpu-host-1
mado-tracking-worker doctor --worker-id gpu-host-1
journalctl --user -u mado-tracking-worker@gpu-host-1 -fdoctorがtokenのscopeのerrorを出す場合は、Service Accountのtokenにread、worker:execute、artifacts:writeがあるかを確かめます。- tokenが401になる場合は、期限切れか、Service Accountが無効になっていないかを確かめます。新しいtokenは
mado-tracking-worker install --token-fileで差し替えます。 - コンピュータの接続確認は、［コンピュータを追加］や［再確認］の［接続に使うworker］で選んだworkerが行います。workerを選んでいない確認は、
MMT_WORKER_TARGET_IDSにそのコンピュータを含むworkerだけが行います。 - ［接続に使うworker］にworkerが出ないときは、workerがオンラインか、新しい版か（
mado-tracking-worker upgrade）を確かめます（SSH・Localのコンピュータ）。
詳しくはworkerを参照してください。
コンピュータが実行先に出ない・Jobを作れない（target_not_available）
- 実行先には、自分が使えるコンピュータだけが出ます。全体設定の「コンピュータ」の［自分が使えるか］で確かめます。
- ほかの人のPrivateのコンピュータは使えません。全体管理者も同じです。所有者にPublicにしてもらうか、自分のコンピュータを足します。
- 自動実行ルール・フック・Sweepは、それぞれの所有者で判定します。ルールをService Accountへ移したときは、そのService Accountをコンピュータの所有者が作ったかを確かめます。
- 待機中のJobが
submit_failedで失敗したときは、Jobを作ったあとでコンピュータがPrivateに変わった可能性があります。 - siteのjob shell・鍵・自分の設定を開いて403
target_not_availableになるのも、そのコンピュータを使えないためです。
詳しくはコンピュータと公開範囲を参照してください。
Runの終了後の処理が欠けている
出力モデルの登録など、Runの終了後の処理が失敗すると、APIの標準エラー出力に次の1行が出ます。Runの終了とGPUの解放は確定しています。自動では再実行しないので、そのRunの登録記録や自動実行の記録が欠けていないかを確かめてください。
{"event":"run_completion_handler_failed","handler":"<処理の名前>","runId":"<Run ID>","message":"<エラー>"}保存先のArtifactが503になる
MMT_STORAGE_SECRET_KEYを変えると、画面で追加したS3の保存先のシークレットを復号できなくなります。APIの起動時にstorage_backend_unavailableがログに出ます。「全体管理」→［ストレージ］で、各S3の保存先のシークレットを入れ直してください（保存先）。