Codici di uscita di curl — significato e rimedi, ricercabili per numero (tutti i codici)
Cercate per numero il codice di uscita di curl, da 1 a 99, e trovate subito significato, cause più frequenti e rimedi concreti. Un riferimento per sviluppatori che copre tutti i codici, compresi il 22, il 28 e il 52, pensato per l'analisi degli errori nell'integrazione continua e nelle esecuzioni pianificate.
Tabella dei codici di uscita di curl
| Codice | Nome della costante | Significato | Cause più frequenti |
|---|---|---|---|
| Errori di connessione e inizializzazione | |||
| 1 | CURLE_UNSUPPORTED_PROTOCOL | Indica che curl non supporta il protocollo indicato nell'indirizzo. | Si sta usando un eseguibile di curl compilato senza quel protocollo, per esempio gopher o ldap, oppure c'è un errore di digitazione nello schema dell'indirizzo. |
| 2 | CURLE_FAILED_INIT | Indica il fallimento dell'inizializzazione interna di curl. | Un errore di basso livello, raro, dovuto a memoria insufficiente o ad anomalie dell'ambiente. |
| 3 | CURLE_URL_MALFORMAT | Indica che l'indirizzo indicato ha un formato scorretto che curl non riesce a interpretare. | Si verifica quando manca lo schema, per esempio il prefisso http://, o quando l'indirizzo contiene caratteri non ammessi. |
| 5 | CURLE_COULDNT_RESOLVE_PROXY | Indica il fallimento della risoluzione del nome host del servente intermediario. | Nome host errato nell'opzione --proxy oppure impossibilità di risolvere il nome tramite il sistema dei nomi previsto per l'intermediario. |
| 6 | CURLE_COULDNT_RESOLVE_HOST | Indica il fallimento della risoluzione del nome dell'host di destinazione. | Errore di digitazione nel nome di dominio, guasto del servente dei nomi o esecuzione in un ambiente privo di connessione. |
| 7 | CURLE_COULDNT_CONNECT | Indica che il nome è stato risolto ma non è stato possibile stabilire la connessione TCP con il servente. | Numero di porta errato, blocco da parte del filtro di rete o servente non in funzione. |
| 8 | CURLE_WEIRD_SERVER_REPLY | Indica la ricezione dal servente di una risposta inattesa, che curl non riesce a interpretare. | Si verifica facilmente quando un servente FTP restituisce una risposta non conforme allo standard o quando ci si collega per errore a un servente che parla un altro protocollo. |
| 9 | CURLE_REMOTE_ACCESS_DENIED | Indica che la connessione al servente è riuscita ma l'accesso è stato negato. | Permessi insufficienti su una cartella FTP oppure restrizioni per indirizzo IP imposte dal servente. |
| Errori di trasferimento dei dati | |||
| 18 | CURLE_PARTIAL_FILE | Indica che il trasferimento è stato interrotto prima del termine e il file è stato ricevuto solo in parte. | Un'interruzione momentanea della rete oppure la chiusura della connessione da parte del servente prima della lunghezza annunciata nell'intestazione Content-Length. |
| 23 | CURLE_WRITE_ERROR | Indica il fallimento della scrittura dei dati sul disco locale o verso la funzione di richiamo. | Spazio su disco insufficiente o mancanza dei permessi di scrittura sul file di destinazione. |
| 26 | CURLE_READ_ERROR | Indica il fallimento della lettura del file locale da caricare. | Il file indicato con -T o --upload-file non esiste oppure mancano i permessi di lettura. |
| 52 | CURLE_GOT_NOTHING | Indica che la connessione al servente è riuscita ma non è giunta alcuna risposta. | Il processo del servente si è interrotto durante l'elaborazione della richiesta oppure una configurazione difettosa gli fa restituire una risposta vuota. |
| 55 | CURLE_SEND_ERROR | Indica il fallimento dell'invio dei dati sulla rete. | La controparte ha chiuso la connessione subito dopo averla stabilita, oppure c'è un'anomalia nell'interfaccia di rete locale. |
| 56 | CURLE_RECV_ERROR | Indica il fallimento della ricezione dei dati dalla rete. | Si osserva soprattutto quando la controparte reimposta inaspettatamente la connessione durante lo scambio. |
| 63 | CURLE_FILESIZE_EXCEEDED | Indica che la dimensione del file supera il limite fissato con --max-filesize. | Si verifica quando si tenta di scaricare una risposta più voluminosa del previsto e scatta il limite impostato per prudenza. |
| 78 | CURLE_REMOTE_FILE_NOT_FOUND | Indica che il file richiesto non esiste sul servente remoto, per esempio in FTP. | Errore di digitazione nel percorso FTP oppure file già eliminato o spostato. |
| Errori dei certificati SSL/TLS | |||
| 35 | CURLE_SSL_CONNECT_ERROR | Indica che durante la negoziazione SSL/TLS si è verificato un problema e la connessione non è stata stabilita. | Si verifica facilmente quando servente e cliente non condividono alcuna versione di TLS o alcuna suite crittografica. |
| 51 | CURLE_PEER_FAILED_VERIFICATION | Indica il fallimento della verifica del certificato del servente, per esempio perché non corrisponde al nome host. | Accesso a un certificato autofirmato oppure nome comune o nome alternativo del certificato diverso dal nome host di destinazione. |
| 58 | CURLE_SSL_CERTPROBLEM | Indica un problema nel certificato del cliente indicato localmente. | Formato non valido del file indicato con --cert oppure errore nell'inserimento della frase d'accesso. |
| 60 | CURLE_SSL_CACERT | Indica l'impossibilità di verificare la catena di certificati dell'autorità necessaria a convalidare quello del servente. | Insieme dei certificati delle autorità non aggiornato oppure autorità autofirmata, per esempio quella di un intermediario aziendale, non presente fra quelle attendibili. Esiste il ripiego -k, ossia --insecure, ma se ne sconsiglia l'uso in produzione. |
| Errori HTTP e di autenticazione | |||
| 22 | CURLE_HTTP_RETURNED_ERROR | Indica che, con l'opzione -f o --fail attiva, la risposta HTTP recava uno stato d'errore della serie 400 o superiore. | Si provoca di proposito, per rilevare gli errori, quando negli script dell'integrazione continua si usa curl -f e l'interfaccia risponde con uno stato d'errore. |
| 67 | CURLE_LOGIN_DENIED | Indica che l'accesso al servente, cioè l'autenticazione, è stato rifiutato. | Nome utente o parola d'ordine errati, oppure blocco dell'utenza su servizi come FTP o SMTP. |
| Altri | |||
| 27 | CURLE_OUT_OF_MEMORY | Indica il fallimento dell'allocazione di memoria durante l'esecuzione di curl. | Situazione rara, per esempio il tentativo di trattare file enormi in un ambiente con poca memoria. |
| 28 | CURLE_OPERATION_TIMEDOUT | Indica che l'operazione non si è conclusa entro il limite di tempo fissato con --connect-timeout, --max-time o simili. | Risposta lenta del servente, latenza di rete o limite di tempo troppo stretto: è uno degli errori più frequenti nell'integrazione continua. |
| 47 | CURLE_TOO_MANY_REDIRECTS | Indica il superamento del numero massimo di reindirizzamenti fissato con --max-redirs. | Un ciclo di reindirizzamenti, con risposte 301 o 302 che si rincorrono, oppure una catena legittima più lunga del limite predefinito di cinquanta. |
Consigli
- Il codice di uscita si legge subito dopo con
$?in Bash o%errorlevel%in Windows. Negli script di shell è comodo usarlo per le diramazioni, per esempio concurl ... || echo "fallito con $?". - Il 28, cioè il tempo scaduto, e il 7, cioè la connessione fallita, si confondono facilmente: il 28 riguarda una risposta lenta dopo la connessione, il 7 il caso in cui la connessione TCP non si stabilisce affatto.
- Di fronte al 60, l'errore del certificato dell'autorità, non aggirate il problema con
-ko--insecure: verificate anzitutto che l'insieme dei certificati delle autorità sia aggiornato. L'uso abituale di -k in produzione aumenta il rischio di attacchi con interposizione. - Il 22, l'errore HTTP, si presenta soltanto con l'opzione
-fo--fail. Senza di essa curl restituisce il codice di uscita 0, cioè successo, anche ricevendo un 404 o un 500: per rilevare gli insuccessi nell'integrazione continua aggiungete sempre -f.
Domande frequenti
Subito dopo l'esecuzione del comando: con
echo $? in Bash e Zsh, con echo %errorlevel% nel prompt dei comandi di Windows e con $LASTEXITCODE in PowerShell.Rivedete anzitutto i valori di
--connect-timeout e --max-time, allungandoli se necessario. Se la lentezza del servente è costante, verificate anche il suo carico di lavoro e il percorso di rete, compresi eventuali intermediari o reti private virtuali.No, sono due cose diverse. Il codice di stato HTTP, per esempio 404 o 500, è la risposta a livello di protocollo restituita dal servente; il codice di uscita di curl riguarda l'esito dell'esecuzione del comando stesso, come una connessione fallita o un tempo scaduto. Poiché curl considera per impostazione predefinita gli errori HTTP come codice di uscita 0, cioè successo, occorre attenzione a non confonderli.
Aggiungendo l'opzione
curl -f, ossia --fail, il comando restituisce il codice di uscita 22 quando la risposta HTTP appartiene alla serie 400 o superiore. Senza quell'opzione, il semplice fatto di aver scaricato correttamente una pagina d'errore produce un codice di uscita pari a 0.Il 6, COULDNT_RESOLVE_HOST, è l'errore della fase in cui il sistema dei nomi non riesce a tradurre il nome host in un indirizzo IP; il 7, COULDNT_CONNECT, è quello della fase successiva, in cui la risoluzione è riuscita ma non si stabilisce la connessione TCP verso quell'indirizzo.
A proposito — l'ordinamento dei codici di uscita di curl
curl è uno strumento a riga di comando il cui sviluppo cominciò nel 1996 per opera di Daniel Stenberg; all'inizio si chiamava «httpget». Oggi è presente di serie in praticamente tutte le distribuzioni Linux, in macOS e in Windows a partire dalla versione 10, ed è uno degli strumenti più elementari per chi sviluppa per il web.
L'ordinamento dei codici di uscita corrisponde esattamente all'enumerazione interna degli errori di libcurl, CURLcode, definita come una successione numerata che comincia da CURLE_OK, cioè il successo, con codice di uscita 0. I numeri mancanti si spiegano con i codici d'errore che nel corso dello sviluppo sono stati sconsigliati o accorpati.
È interessante notare che i codici di uscita di curl seguono un ordinamento proprio, indipendente dalla consuetudine POSIX secondo cui 0 indica il successo e 1 un errore generico. Quando in uno script di shell si trattano insieme i codici di uscita di più comandi occorre perciò verificarne il significato sul manuale di ciascuno strumento.