Risolvere i problemi di autenticazione e trasferimento della CLI dosya

Esegui un comando in sola lettura prima di riprovare un trasferimento. La CLI dosya distingue errori di utilizzo, autenticazione, rete, permessi e manutenzione tramite codici di uscita: conserva il messaggio e $?/%ERRORLEVEL% invece di creare una nuova chiave a ogni rifiuto.

Procedura

Esegui questi comandi nell’ordine:

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

Se --version non funziona, l’eseguibile manca, è bloccato o non è nel PATH. Se --help funziona ma whoami no, il binario si avvia e il problema riguarda configurazione, rete o autorizzazione. whoami mostra nome, email, ID dell’account autenticato e numero di spazi di lavoro; verifica l’identità prima di scrivere dati.

Usa --debug per stampare su stderr il metodo della richiesta, l’URL, il tentativo e lo stato HTTP. La chiave API non viene stampata intenzionalmente, ma controlla l’output prima di condividerlo: comandi, percorsi e messaggi del server possono comunque rivelare nomi privati. --json mantiene su stdout i risultati leggibili da sistemi automatici, mentre la diagnostica resta su stderr.

Risolvi problemi di credenziali e origine API

La precedenza delle credenziali è --key, poi DOSYA_API_KEY, quindi la configurazione salvata. Una variabile d’ambiente obsoleta può quindi prevalere su un nuovo accesso salvato. Controlla l’ambiente ed esegui di nuovo dosya whoami senza sostituzioni indesiderate.

L’indirizzo API predefinito è https://api.dosya.dev. DOSYA_API_BASE prevale sulla configurazione salvata e sul valore predefinito. Se punta al sito promozionale o a un altro endpoint HTML, un messaggio 4xx include the API returned a non-JSON response - check DOSYA_API_BASE e l’origine configurata.

Usa dosya auth login per la richiesta interattiva nascosta oppure passa una chiave tramite pipe con dosya auth login --key -. Passare il valore letterale tramite --key <key> lo espone alla cronologia della shell e all’elenco dei processi. Le chiavi devono iniziare con dos_; creale su https://app.dosya.dev/profile/api.

Messaggio / uscita	Significato	Azione corretta
Not authenticated. Run: dosya auth login / uscita 3	Nessuna chiave disponibile da opzione, ambiente o configurazione salvata	Autenticati o imposta DOSYA_API_KEY per quel processo.
Authentication failed. Run ‘dosya auth login’ to re-authenticate. / uscita 3	Il server ha restituito 401; chiave non valida, scaduta o revocata	Sostituisci la credenziale e riprova whoami.
Messaggio di permesso del server / uscita 5	Il server ha restituito 403; credenziale valida, ma ambito, protocollo, regola IP/oraria, appartenenza o ruolo hanno rifiutato l’operazione	Correggi la restrizione indicata. Autenticarsi di nuovo con gli stessi permessi causa un ciclo.
Cannot reach … Check your internet connection. / uscita 4	Errore DNS, di connessione o trasporto	Controlla rete e indirizzo API, poi riprova una richiesta in sola lettura.
Request timed out after …s. / uscita 4	La richiesta ha superato il timeout	Verifica stato del servizio e rete; aumenta --timeout <seconds> solo se l’operazione richiede prevedibilmente più tempo.
The dosya CLI is paused for maintenance. / uscita 75	Un interruttore amministrativo della piattaforma ha disabilitato le richieste CLI	Nulla è stato caricato o modificato; controlla https://status.dosya.dev e riprova più tardi.

Il percorso di configurazione salvata è mostrato da dosya config path. Su macOS/Linux si trova normalmente in ~/.dosya/config.json o $XDG_CONFIG_HOME/dosya/config.json con modalità 0600. Se la CLI avvisa che altri utenti possono leggere il file, applica il comando chmod 600 mostrato e sostituisci una chiave che potrebbe essere stata esposta.

Correggi il contesto dello spazio di lavoro

Esegui dosya workspace list e copia l’ID dello spazio di lavoro desiderato. dosya workspace use <id> salva un valore predefinito ma non contatta il server per verificare l’ID, quindi confermalo con:

dosya ls --workspace ws_example

Durante la diagnosi, specificare --workspace è più sicuro che usare un valore predefinito obsoleto. Workspace ID required termina con codice 2 senza effettuare richieste. Un 403 dopo aver scelto uno spazio di lavoro reale indica un problema di appartenenza, ruolo o ambito di accesso della chiave; un 404 può indicare che la risorsa o il percorso non esistono più o non sono visibili.

Diagnostica gli errori di caricamento

Prima di riprovare, confronta il nome e la dimensione del file locale e la destinazione con le regole di caricamento dello spazio di lavoro e lo spazio disponibile. Quando l’endpoint è disponibile, la CLI controlla in anticipo le estensioni consentite o bloccate, la dimensione massima e lo spazio rimanente; la decisione finale spetta al server.

dosya upload carica per impostazione predefinita tre file contemporaneamente, accetta --parallel fino a 16 e lo limita ulteriormente al limite attivo dello spazio di lavoro. Se non c’è posto, attende 0,5, 1,5, 3, 5 e 8 secondi prima di restituire il rifiuto del server. Altri dispositivi e sessioni in attesa condividono la capacità.

Per i piccoli caricamenti in streaming, la CLI riprova tre volte dopo errori di trasporto o 5xx, attendendo 1, 3 e 8 secondi e ricreando ogni volta il flusso. Per i file oltre la soglia multipart conserva un file ausiliario .dosya-upload, così ripetere la stessa origine può riprendere le parti caricate. Conservalo accanto al file invariato fino al completamento; cambiare la dimensione dell’origine o l’origine API rende la sessione salvata non idonea.

Le richieste di metadati hanno un timeout predefinito di 30 secondi. Caricamenti e download usano valori predefiniti più lunghi e specifici per l’operazione, inclusi 10 minuti per caricare un intero file, salvo impostare esplicitamente un altro valore globale con --timeout. Un 4xx è un rifiuto dovuto alle regole o ai dati inviati e non si risolve ripetendo gli stessi byte.

Il client HTTP riprova automaticamente GET, HEAD e PUT dopo errori 5xx o di trasporto idonei, con ritardi di 1, 3 e 8 secondi. Non ripete alla cieca POST, che potrebbe creare duplicati, né DELETE, perché una seconda eliminazione può diventare permanente. Dopo un errore ambiguo di scrittura, controlla dosya prima di ripetere il comando.

Risultato previsto

1. Verifica che dosya whoami riporti l’account desiderato.
2. Elenca la destinazione specificando l’ID dello spazio di lavoro.
3. Riprova con un file innocuo dal nome univoco e il minor numero praticabile di operazioni simultanee.
4. Apri File in dosya, controlla nome, dimensione e cartella, poi scarica e confronta il campione se l’integrità è importante.

Se lo stesso comando minimo non funziona, invia privatamente all’assistenza la versione CLI, il sistema operativo, il comando esatto senza segreti, il codice di uscita, ora e fuso orario approssimativi, l’ID dello spazio di lavoro, dimensione del file e l’output di debug o di errore ripulito. Non includere mai la chiave completa, dump dell’ambiente, file di configurazione o byte di file riservati.

Guide correlate

• Installare la CLI
• Autenticare la CLI
• Scegliere uno spazio di lavoro