dosya CLIの認証と転送のトラブルシューティング

転送を再試行する前に読み取り専用コマンドを実行してください。dosya CLIは使い方、認証、ネットワーク、権限、メンテナンスの問題を終了コードで区別します。拒否されるたびに新しいキーを作成せず、メッセージと$?／%ERRORLEVEL%を控えてください。

手順

次の順に実行してください。

dosya --version
dosya --help
dosya whoami
dosya workspace list
dosya ls --workspace REPLACE_WITH_WORKSPACE_ID

--versionが実行できない場合、実行ファイルがない、ブロックされている、またはPATHに含まれていません。--helpは成功してwhoamiが失敗する場合、実行ファイルは起動しており、設定、ネットワーク、または認可に問題があります。whoamiには認証された名前、メールアドレス、アカウントID、ワークスペース数が表示されます。書き込み前に自分の情報か確認してください。

--debugを使うと、リクエストメソッド、URL、試行回数、HTTPステータスがstderrに出力されます。APIキーを意図的に出力することはありませんが、コマンドやパス、サーバーメッセージから非公開の名前が分かる場合があるため、共有前に出力を確認してください。--jsonでは機械可読の結果はstdoutに、診断情報はstderrに出力されます。

認証情報とAPIオリジンの問題を解決する

認証情報の優先順位は--key、DOSYA_API_KEY、保存済み設定の順です。そのため古い環境変数が新しく保存した認証情報より優先されることがあります。環境を確認し、意図しない上書きがない状態でdosya whoamiを再実行してください。

通常のAPIベースはhttps://api.dosya.devです。DOSYA_API_BASEは保存済み設定と既定値の両方より優先されます。マーケティングサイトや別のHTMLエンドポイントを指している場合、4xxメッセージにthe API returned a non-JSON response - check DOSYA_API_BASEと設定されたオリジンが表示されます。

入力内容が表示されない対話プロンプトを使うにはdosya auth loginを使用するか、dosya auth login --key -でキーをパイプしてください。--key <key>にキーを直接渡すと、シェル履歴とプロセス一覧に公開されます。キーはdos_で始まる必要があります。https://app.dosya.dev/profile/apiで作成してください。

メッセージ／終了コード	意味	対処
Not authenticated. Run: dosya auth login / exit 3	フラグ、環境変数、保存済みキーのいずれも利用できません	認証するか、そのプロセスにDOSYA_API_KEYを設定してください。
Authentication failed. Run ‘dosya auth login’ to re-authenticate. / exit 3	サーバーが401を返しました。キーが無効、期限切れ、または無効化されています	認証情報を交換し、whoamiを再確認してください。
サーバーの権限メッセージ / exit 5	サーバーが403を返しました。認証情報は有効ですが、スコープ、プロトコル、IP／時間ルール、メンバーシップ、またはロールにより拒否されました	示された制限を修正してください。同じ権限で再認証しても繰り返されます。
Cannot reach … Check your internet connection. / exit 4	DNS、接続、または通信に問題があります	ネットワークとAPIベースを確認し、読み取り専用リクエストを再試行してください。
Request timed out after …s. / exit 4	リクエストが制限時間を超えました	サービスとネットワークの状態を確認し、操作により長い時間が必要な場合にのみ--timeout <seconds>を増やしてください。
The dosya CLI is paused for maintenance. / exit 75	管理者によるプラットフォーム設定でCLIリクエストが無効になっています	アップロードや変更は行われていません。https://status.dosya.devを確認し、後で再実行してください。

保存済み設定のパスはdosya config pathで確認できます。macOS/Linuxでは通常、~/.dosya/config.jsonまたは$XDG_CONFIG_HOME/dosya/config.jsonにあり、モードは0600です。他のユーザーがファイルを読み取れるとCLIが警告した場合、表示されたchmod 600コマンドを実行し、漏えいした可能性のあるキーを交換してください。

ワークスペースの指定を修正する

dosya workspace listを実行して対象のワークスペースIDをコピーしてください。dosya workspace use <id>は既定値を保存しますが、サーバーに接続してIDを検証しないため、次のコマンドで確認してください。

dosya ls --workspace ws_example

診断中は古い既定値に頼るより--workspaceを明示する方が安全です。Workspace ID requiredの場合はコード2で終了し、リクエストは送信されません。実在するワークスペースを選択後に403が返る場合はメンバーシップ、ロール、またはキーのアクセス範囲に問題があります。404はリソースやパスが存在しないか、表示権限がないことを意味する場合があります。

アップロードの問題を診断する

再試行前に、ローカルファイルの名前とサイズ、保存先をワークスペースのアップロードルールと利用可能なストレージと照らし合わせてください。CLIはエンドポイントが利用可能な場合、許可／禁止された拡張子、最大ファイルサイズ、残りのストレージを事前確認します。最終的な判定はサーバーが行います。

dosya uploadの既定の並行数は3ファイルで、--parallelには最大16を指定できます。ワークスペースの同時アップロードの上限を超える場合は、その上限に制限されます。空きがない場合は0.5秒、1.5秒、3秒、5秒、8秒待機してからサーバーの拒否を返します。この枠は他のデバイスや保留中のセッションと共有されます。

小さいファイルのストリームアップロードでは、通信または5xxの問題が発生すると1秒、3秒、8秒後に3回再試行し、その都度ストリームを作り直します。マルチパートのしきい値を超えるファイルでは.dosya-uploadサイドカーファイルが残るため、同じ元ファイルで再実行するとアップロード済みのパートから再開できます。完了まで元ファイルを変更せず、その隣にサイドカーファイルを保持してください。元ファイルのサイズやAPIオリジンを変更すると、保存済みセッションは使えなくなります。

メタデータリクエストの既定のタイムアウトは30秒です。アップロードとダウンロードには操作ごとの長い既定値があり、ファイル全体のアップロードは10分です。グローバルオプションの--timeoutを明示的に指定するとこれらに代わって適用されます。4xxはポリシーまたは入力による拒否であり、同じデータを再送しても解決しません。

HTTPクライアントは対象となる5xxまたは通信の問題に対し、GET、HEAD、PUTを1秒、3秒、8秒の間隔で自動的に再試行します。POSTを無条件に再送すると重複が生じる可能性があり、DELETEを繰り返すと完全削除になる可能性があるため、これらは自動で再送しません。書き込み結果が不明なエラーの後は、コマンドを再実行する前にdosyaを確認してください。

期待される結果

1. dosya whoamiに対象のアカウントが表示されることを確認してください。
2. ワークスペースIDを明示して対象を一覧表示してください。
3. 一意の名前を付けた無害なファイル1件を、実用上可能な最小の並行数で再試行してください。
4. dosyaのファイルを開き、名前、サイズ、フォルダーを確認してください。整合性が重要な場合はサンプルをダウンロードして比較してください。

同じ最小限のコマンドが失敗する場合は、非公開のサポート窓口にCLIのバージョン、OS、秘密情報を除いた正確なコマンド、終了コード、おおよその時刻とタイムゾーン、ワークスペースID、ファイルサイズ、機密情報を除いたデバッグ／エラー出力を送ってください。キーの全体、環境変数のダンプ、設定ファイル、機密ファイルのデータは絶対に含めないでください。

関連ガイド

• CLIをインストールする
• CLIを認証する
• ワークスペースを選択する