curl-virhekoodit: Täydellinen hakuteos

Kun curl-komento epäonnistuu, se palauttaa numeerisen paluukoodin (kutsutaan myös curl-virhekoodiksi), joka tunnistaa virheen tyypin. Voit tarkistaa curlin paluukoodin ajamalla echo $? heti curl-komennon jälkeen (tai $LASTEXITCODE PowerShellissä). Paluukoodi 0 tarkoittaa onnistumista; mikä tahansa muu luku osoittaa tietyn ongelman — DNS-resoluution epäonnistumisista ja yhteyden aikakatkaisuista SSL-sertifikaattiongelmiin. Tämä sivu on täydellinen hakuteos yleisimmistä curl-virhekoodeista selityksineen, syineen ja korjauksineen. Jos työskentelet curl-komentojen kanssa koodissasi, liitä ne curl2codeen muuntaaksesi ne valitsemallesi ohjelmointikielelle.

Pikaviitetaulukko

Paluukoodi	Virheen nimi	Kuvaus
0	CURLE_OK	Onnistui. Toiminto suoritettiin ilman virheitä.
1	CURLE_UNSUPPORTED_PROTOCOL	Protokollaa ei tueta. URL käyttää protokollaa, jota curl ei ole käännetty tukemaan.
3	CURLE_URL_MALFORMAT	Virheellinen URL. URL-syntaksi on virheellinen tai sitä ei voitu jäsentää.
5	CURLE_COULDNT_RESOLVE_PROXY	Välityspalvelinta ei voitu selvittää. Määritetyn välityspalvelimen isäntänimeä ei voitu selvittää.
6	CURLE_COULDNT_RESOLVE_HOST	DNS-haku epäonnistui — isäntänimeä ei voitu selvittää IP-osoitteeksi.
7	CURLE_COULDNT_CONNECT	TCP-yhteys epäonnistui — palvelin on alhaalla, portti on estetty tai palomuuri hylkää yhteydet.
18	CURLE_PARTIAL_FILE	Osittainen tiedosto. Siirto keskeytyi ja vain osa tiedostosta vastaanotettiin.
22	CURLE_HTTP_RETURNED_ERROR	Palvelin palautti HTTP-virheen (4xx/5xx) ja --fail-lippu oli käytössä.
23	CURLE_WRITE_ERROR	Kirjoitusvirhe. curl ei pystynyt kirjoittamaan vastaanotettua dataa levylle (käyttöoikeus evätty tai levy täynnä).
28	CURLE_OPERATION_TIMEDOUT	Toiminto ylitti suurimman sallitun ajan (DNS, yhteys tai siirto).
35	CURLE_SSL_CONNECT_ERROR	SSL/TLS-kättely epäonnistui — protokollaversio- tai salakirjoituspakettiristiriita.
37	CURLE_FILE_COULDNT_READ_FILE	Tiedostoa ei voitu lukea. Pyynnössä viitattua paikallista tiedostoa ei voitu avata tai lukea.
52	CURLE_GOT_NOTHING	Tyhjä vastaus palvelimelta. Palvelin sulki yhteyden lähettämättä mitään dataa.
56	CURLE_RECV_ERROR	Yhteys katkaistiin — palvelin katkaisi yhteyden tiedonsiirron aikana.
60	CURLE_SSL_CACERT	SSL-sertifikaatin vahvistus epäonnistui — vanhentunut, itse allekirjoitettu tai CA-nippu on vanhentunut.
77	CURLE_SSL_CACERT_BADFILE	SSL CA -sertifikaattiongelma. Määritettyä CA-sertifikaattitiedostoa ei voitu lukea tai jäsentää.
92	CURLE_HTTP2_STREAM	HTTP/2-virtavirhe. HTTP/2-protokollatason virtavirhe tapahtui siirron aikana.

0CURLE_OK

Onnistui. Toiminto suoritettiin ilman virheitä.

1CURLE_UNSUPPORTED_PROTOCOL

Protokollaa ei tueta. URL käyttää protokollaa, jota curl ei ole käännetty tukemaan.

3CURLE_URL_MALFORMAT

Virheellinen URL. URL-syntaksi on virheellinen tai sitä ei voitu jäsentää.

5CURLE_COULDNT_RESOLVE_PROXY

Välityspalvelinta ei voitu selvittää. Määritetyn välityspalvelimen isäntänimeä ei voitu selvittää.

6CURLE_COULDNT_RESOLVE_HOST

DNS-haku epäonnistui — isäntänimeä ei voitu selvittää IP-osoitteeksi.

7CURLE_COULDNT_CONNECT

TCP-yhteys epäonnistui — palvelin on alhaalla, portti on estetty tai palomuuri hylkää yhteydet.

18CURLE_PARTIAL_FILE

Osittainen tiedosto. Siirto keskeytyi ja vain osa tiedostosta vastaanotettiin.

22CURLE_HTTP_RETURNED_ERROR

Palvelin palautti HTTP-virheen (4xx/5xx) ja --fail-lippu oli käytössä.

23CURLE_WRITE_ERROR

Kirjoitusvirhe. curl ei pystynyt kirjoittamaan vastaanotettua dataa levylle (käyttöoikeus evätty tai levy täynnä).

28CURLE_OPERATION_TIMEDOUT

Toiminto ylitti suurimman sallitun ajan (DNS, yhteys tai siirto).

35CURLE_SSL_CONNECT_ERROR

SSL/TLS-kättely epäonnistui — protokollaversio- tai salakirjoituspakettiristiriita.

37CURLE_FILE_COULDNT_READ_FILE

Tiedostoa ei voitu lukea. Pyynnössä viitattua paikallista tiedostoa ei voitu avata tai lukea.

52CURLE_GOT_NOTHING

Tyhjä vastaus palvelimelta. Palvelin sulki yhteyden lähettämättä mitään dataa.

56CURLE_RECV_ERROR

Yhteys katkaistiin — palvelin katkaisi yhteyden tiedonsiirron aikana.

60CURLE_SSL_CACERT

SSL-sertifikaatin vahvistus epäonnistui — vanhentunut, itse allekirjoitettu tai CA-nippu on vanhentunut.

77CURLE_SSL_CACERT_BADFILE

SSL CA -sertifikaattiongelma. Määritettyä CA-sertifikaattitiedostoa ei voitu lukea tai jäsentää.

92CURLE_HTTP2_STREAM

HTTP/2-virtavirhe. HTTP/2-protokollatason virtavirhe tapahtui siirron aikana.

Virhe 6: Isäntäkonetta ei voitu selvittää

Mitä se tarkoittaa: Terminaalissasi näkyy curl: (6) Could not resolve host. curl ei pystynyt selvittämään isäntänimeä IP-osoitteeksi — DNS-haku epäonnistui ennen kuin yhteyttä yritettiin muodostaa.
Syyt: Yleisimmät syyt ovat: kirjoitusvirhe isäntänimessä (esim. curl https://apiexample.com eikä api.example.com), DNS-palvelinongelmat (määritetty DNS on alhaalla tai tavoittamattomissa), ei verkkoyhteyttä (Wi-Fi katkaistu, VPN ei yhdistetty) tai verkkotunnus todella ei ole olemassa.
Miten korjata: Tarkista ensin, että URL on oikein. Testaa sitten DNS-resoluutio suoraan: nslookup api.example.com tai dig api.example.com. Jos DNS epäonnistuu, kokeile toista DNS-palvelinta: curl --dns-servers 8.8.8.8 https://api.example.com. Tarkista /etc/resolv.conf tai verkkoasetukset. Jos olet yrityksen VPN:n takana, varmista, että sisäinen DNS pystyy selvittämään isännän.

$ curl https://api.exmple.com/users

Virhe 7: Yhteyden muodostaminen epäonnistui

Mitä se tarkoittaa: Terminaalissasi näkyy curl: (7) Failed to connect to host port: Connection refused. curl selvitti isäntänimen, mutta ei pystynyt muodostamaan TCP-yhteyttä palvelimeen — yhteys hylättiin aktiivisesti tai aikakatkaistiin TCP-tasolla.
Syyt: Yleisiä syitä ovat: palvelin on alhaalla tai ei käynnissä, palomuuri estää portin (tarkista sekä paikallinen että palvelinpuolen palomuuri), portti on väärä (esim. palvelu toimii portissa 8080, mutta yhdistät porttiin 443), tai palvelimen kuuntelujono on täynnä suuren kuorman alla.
Miten korjata: Varmista, että palvelin on käynnissä: ping api.example.com ja telnet api.example.com 443. Tarkista, onko oikea portti auki: nmap -p 443 api.example.com. Poista paikallinen palomuuri väliaikaisesti käytöstä testataksesi. Jos käytät Dockeria, varmista, että kontin portti on julkaistu. Kokeile verbose-tilassa: curl -v https://api.example.com nähdäksesi tarkalleen, missä yhteys epäonnistuu.

$ curl https://localhost:8080/api

Virhe 22: HTTP palautti virheen

Mitä se tarkoittaa: Terminaalissasi näkyy curl: (22) The requested URL returned error. Palvelin palautti HTTP-virhetilanteen (4xx tai 5xx) ja curlia kutsuttiin -f- tai --fail-lipulla, joka käskee curlia käsittelemään HTTP-virheet epäonnistumisina.
Syyt: Virheen laukaisevat HTTP-tilakoodit kuten 400 (Bad Request), 401 (Unauthorized), 403 (Forbidden), 404 (Not Found) tai 500 (Internal Server Error) — mutta vain kun --fail on käytössä. Ilman --fail-lippua curl palauttaa koodin 0 myös HTTP-virheiden yhteydessä. Yleisiä syitä: väärä URL, puuttuva todennus, riittämättömät oikeudet tai palvelinpuolen virheet.
Miten korjata: Aja curl ilman --fail-lippua nähdäksesi koko vastauksen rungon — se sisältää usein varsinaisen virheviestin. Tarkista HTTP-tilakoodi: curl -w "%{http_code}" -o /dev/null -s URL. 401/403-virheille: varmista todennustunniste tai API-avain. 404-virheelle: tarkista URL-polku. 500-virheelle: ongelma on palvelinpuolella.

$ curl --fail https://api.example.com/nonexistent

Virhe 28: Toiminto aikakatkaistiin

Mitä se tarkoittaa: Terminaalissasi näkyy curl: (28) Operation timed out tai curl: (28) Connection timed out. Toiminto kesti kauemmin kuin sallittu aika. Tämä on yleisin curl-virhe — se voi ilmetä DNS-resoluution, TCP-yhteyden, SSL-kättelyn tai tiedonsiirron aikana.
Syyt: Tyypillisiä syitä ovat: hidas tai ylikuormitettu palvelin, joka ei vastaa ajoissa, verkon ruuhkautuminen tai pakettihävikki, palomuuri hylkää paketit hiljaisesti (ei hylkäystä, vain hiljaisuutta), liian tiukat aikakatkaisuarvot --connect-timeout- tai --max-time-lipuilla, tai välipalvelimen virheellinen konfiguraatio.
Miten korjata: Kasvata aikakatkaisua: curl --connect-timeout 30 --max-time 120 URL. Käytä verbose-tilaa nähdäksesi, missä se juuttuu: curl -v URL. Testaa verkon viive: ping api.example.com ja traceroute api.example.com. Jos olet välipalvelimen takana, kokeile ohittaa se: curl --noproxy '*' URL. Suurille tiedostosiirroille harkitse --retry 3 ja --retry-delay 5 automaattisia uudelleenyrityksiä.

$ curl --connect-timeout 5 https://slow-api.example.com/data

Virhe 35: SSL-yhteysvirhe

Mitä se tarkoittaa: Terminaalissasi näkyy curl: (35) SSL connect error. SSL/TLS-kättely epäonnistui — curl ei pystynyt muodostamaan suojattua yhteyttä palvelimeen.
Syyt: Yleisiä syitä: TLS-versioristiriita (palvelin vaatii TLS 1.3, mutta curlisi tukee vain TLS 1.2:ta), salakirjoituspakettiyhteensopimattomuus, palvelimen virheellinen SSL-konfiguraatio (vanhentunut sertifikaatti kättelyn aikana, puutteellinen ketju), palvelin ei oikeasti tue HTTPS:ää kyseisessä portissa, tai välipalvelin tai palomuuri kaappaa SSL-yhteyden (MITM).
Miten korjata: Pakota tietty TLS-versio: curl --tlsv1.2 URL tai curl --tlsv1.3 URL. Tarkista, mitä palvelin tukee: openssl s_client -connect api.example.com:443. Päivitä curl ja OpenSSL uusimpiin versioihin. Jos palvelin käyttää itse allekirjoitettua sertifikaattia, kyseessä on yleensä virhe 60 — virhe 35 viittaa tyypillisesti protokollatason kättelyvirheeseen.

$ curl https://legacy-server.example.com/api

Virhe 56: Vastaanotto epäonnistui — Yhteys katkaistiin

Mitä se tarkoittaa: Terminaalissasi näkyy curl: (56) Recv failure: Connection reset by peer. Yhteys muodostettiin onnistuneesti, mutta tiedon vastaanotto epäonnistui — palvelin sulki tai nollasi yhteyden odottamattomasti siirron aikana.
Syyt: Tämä tapahtuu usein, kun: palvelin kaatuu tai käynnistyy uudelleen siirron aikana, kuormantasaaja tai välipalvelin katkaisee yhteyden (joutoaikakatkaisu, liian suuri pyyntö), palomuuri katkaisee pitkäkestoiset yhteydet, palvelimella on lyhyempi keep-alive-aikakatkaisu kuin odotettiin, tai verkkovika asiakkaan ja palvelimen välillä.
Miten korjata: Yritä pyyntöä uudelleen — hetkelliset verkko-ongelmat ovat yleisin syy. Käytä verbose-tilaa: curl -v URL nähdäksesi tarkan epäonnistumiskohdan. Jos virhe tapahtuu suurten latausten aikana, kokeile osittaista siirtoa: curl -H "Transfer-Encoding: chunked" URL. Git-operaatioille, jotka näyttävät RPC failed; curl 56, kasvata puskuria: git config http.postBuffer 524288000.

$ curl https://api.example.com/large-download

Virhe 60: SSL-sertifikaattiongelma

Mitä se tarkoittaa: Terminaalissasi näkyy curl: (60) SSL certificate problem: unable to get local issuer certificate. curl ei pystynyt vahvistamaan palvelimen SSL-sertifikaattia CA-nipputiedostoa (Certificate Authority) vasten. TLS-kättely suoritettiin protokollatasolla, mutta sertifikaatin vahvistus epäonnistui.
Syyt: Yleisimmät syyt: palvelin käyttää itse allekirjoitettua sertifikaattia, sertifikaatti on vanhentunut, sertifikaattiketju on puutteellinen (välisertifikaatit puuttuvat), curlin CA-nippu on vanhentunut (yleistä vanhoissa järjestelmissä tai Docker-konteissa), tai sertifikaatin Common Name / SAN ei vastaa pyydettyä isäntänimeä.
Miten korjata: Päivitä CA-nippu: curl --cacert /path/to/cacert.pem URL. Lataa päivitetty nippu osoitteesta https://curl.se/ca/cacert.pem. Diagnosoidaksesi: openssl s_client -connect api.example.com:443 -showcerts. Itse allekirjoitetuille sertifikaateille kehityksessä käytä curl -k URL (älä koskaan tuotannossa — se poistaa kaiken sertifikaatin vahvistuksen). Dockerissa asenna ca-certificates-paketti.

$ curl https://self-signed.example.com/api

Muut virhekoodit

Paluukoodi	Virheen nimi	Kuvaus
0	CURLE_OK	Onnistui. Toiminto suoritettiin ilman virheitä.
1	CURLE_UNSUPPORTED_PROTOCOL	Protokollaa ei tueta. URL käyttää protokollaa, jota curl ei ole käännetty tukemaan.
3	CURLE_URL_MALFORMAT	Virheellinen URL. URL-syntaksi on virheellinen tai sitä ei voitu jäsentää.
5	CURLE_COULDNT_RESOLVE_PROXY	Välityspalvelinta ei voitu selvittää. Määritetyn välityspalvelimen isäntänimeä ei voitu selvittää.
18	CURLE_PARTIAL_FILE	Osittainen tiedosto. Siirto keskeytyi ja vain osa tiedostosta vastaanotettiin.
23	CURLE_WRITE_ERROR	Kirjoitusvirhe. curl ei pystynyt kirjoittamaan vastaanotettua dataa levylle (käyttöoikeus evätty tai levy täynnä).
37	CURLE_FILE_COULDNT_READ_FILE	Tiedostoa ei voitu lukea. Pyynnössä viitattua paikallista tiedostoa ei voitu avata tai lukea.
52	CURLE_GOT_NOTHING	Tyhjä vastaus palvelimelta. Palvelin sulki yhteyden lähettämättä mitään dataa.
77	CURLE_SSL_CACERT_BADFILE	SSL CA -sertifikaattiongelma. Määritettyä CA-sertifikaattitiedostoa ei voitu lukea tai jäsentää.
92	CURLE_HTTP2_STREAM	HTTP/2-virtavirhe. HTTP/2-protokollatason virtavirhe tapahtui siirron aikana.

0CURLE_OK

Onnistui. Toiminto suoritettiin ilman virheitä.

1CURLE_UNSUPPORTED_PROTOCOL

Protokollaa ei tueta. URL käyttää protokollaa, jota curl ei ole käännetty tukemaan.

3CURLE_URL_MALFORMAT

Virheellinen URL. URL-syntaksi on virheellinen tai sitä ei voitu jäsentää.

5CURLE_COULDNT_RESOLVE_PROXY

Välityspalvelinta ei voitu selvittää. Määritetyn välityspalvelimen isäntänimeä ei voitu selvittää.

18CURLE_PARTIAL_FILE

Osittainen tiedosto. Siirto keskeytyi ja vain osa tiedostosta vastaanotettiin.

23CURLE_WRITE_ERROR

Kirjoitusvirhe. curl ei pystynyt kirjoittamaan vastaanotettua dataa levylle (käyttöoikeus evätty tai levy täynnä).

37CURLE_FILE_COULDNT_READ_FILE

Tiedostoa ei voitu lukea. Pyynnössä viitattua paikallista tiedostoa ei voitu avata tai lukea.

52CURLE_GOT_NOTHING

Tyhjä vastaus palvelimelta. Palvelin sulki yhteyden lähettämättä mitään dataa.

77CURLE_SSL_CACERT_BADFILE

SSL CA -sertifikaattiongelma. Määritettyä CA-sertifikaattitiedostoa ei voitu lukea tai jäsentää.

92CURLE_HTTP2_STREAM

HTTP/2-virtavirhe. HTTP/2-protokollatason virtavirhe tapahtui siirron aikana.

Miten korjata curl-virheitä

Kun curl epäonnistuu, nämä kolme lippua auttavat tunnistamaan juurisyyn nopeasti — DNS-resoluutiosta SSL-kättelyyn ja vastaussisältöön.

1
Ota käyttöön yksityiskohtainen tuloste
Aja curl -v URL nähdäksesi koko pyyntö/vastaussyklin: DNS-resoluutio, TCP-yhteys, TLS-kättely, lähetetyt pyyntöotsikot ja vastaanotetut vastausotsikot. Tämä on yksittäin hyödyllisin vianmäärityslippu.
2
Tarkista HTTP-tilakoodi
Aja curl -o /dev/null -s -w "%{http_code}" URL saadaksesi pelkän HTTP-tilakoodin (200, 404, 500 jne.) ilman vastauksen runkoa. Hyödyllinen nopeisiin terveystarkistuksiin ja skriptaukseen.
3
Näytä virheet hiljaisesti
Aja curl -sS URL piilottaaksesi edistymispalkin (-s) mutta näyttääksesi silti virheet (-S). Täydellinen skripteille, joissa haluat puhtaan tulosteen mutta tarvitset epäonnistumisten havaitsemisen.

Usein kysytyt kysymykset

Miten tarkistaa curlin paluukoodi?

Curl-komennon ajamisen jälkeen paluukoodi tallennetaan komentotulkin erikoismuuttujaan. Bash/Zsh-ympäristössä aja echo $? heti curl-komennon jälkeen. PowerShellissä käytä $LASTEXITCODE. Skripteissä voit tarkistaa sen ehdolla: if curl -sf URL; then echo "OK"; else echo "Failed with code $?"; fi. Paluukoodi 0 tarkoittaa onnistumista; mikä tahansa muu luku osoittaa virheen. Nähdäksesi sekä HTTP-tilakoodin että curlin paluukoodin, yhdistä curl -w "%{http_code}" -o /dev/null -s URL; echo "Exit: $?". Huomaa, että curlin paluukoodi on eri asia kuin HTTP-tilakoodi — curl palauttaa 0 myös HTTP 404 -vastauksen yhteydessä, ellei käytetä --fail-lippua.

Miten korjata curl-virhe 28 (toiminto aikakatkaistiin)?

Virhe 28 tarkoittaa, että pyyntö ylitti suurimman sallitun ajan. Ensinnäkin kasvata aikakatkaisua: curl --connect-timeout 30 --max-time 120 URL. --connect-timeout rajoittaa TCP-yhteysvaihetta, kun taas --max-time rajoittaa koko toimintoa. Seuraavaksi selvitä pullonkaula komennolla curl -v URL — yksityiskohtainen tuloste näyttää tarkalleen, mihin curl juuttuu (DNS, yhteys, TLS tai siirto). Yleisiä korjauksia: tarkista verkkoyhteys ja DNS-asetukset, varmista että palvelin vastaa (ping ja telnet), ohita välipalvelimet komennolla --noproxy '*', ja suurille latauksille lisää --retry 3 --retry-delay 5 automaattisia uudelleenyrityksiä varten.

Miten korjata curlin SSL-sertifikaattivirheet (virhe 60)?

Virhe 60 tarkoittaa, että curl ei pysty vahvistamaan palvelimen SSL-sertifikaattia. Korjaus riippuu syystä. Vanhentuneelle CA-nipulle: lataa uusi osoitteesta https://curl.se/ca/cacert.pem ja käytä curl --cacert /path/to/cacert.pem URL. Docker-konteille: asenna ca-certificates-paketti (apt-get install ca-certificates). Itse allekirjoitetuille sertifikaateille kehityksessä: käytä curl -k URL ohittaaksesi vahvistuksen — mutta älä koskaan käytä -k-lippua tuotannossa, sillä se poistaa kaiken sertifikaattitarkistuksen. Diagnosoidaksesi: aja openssl s_client -connect host:443 -showcerts tarkastaaksesi sertifikaattiketjun. Jos sertifikaatti on vanhentunut tai isäntänimi ei täsmää, ongelma on palvelinpuolella.

Mitä curl-virhe 7 (yhteyden muodostaminen epäonnistui) tarkoittaa?

Virhe 7 tarkoittaa, että curl selvitti isäntänimen IP-osoitteeksi, mutta ei pystynyt muodostamaan TCP-yhteyttä. Palvelin hylkäsi yhteyden aktiivisesti tai yhteysyritys aikakatkaistiin verkkotasolla. Yleisiä syitä: palvelu ei ole käynnissä kohdeisännällä (tarkista komennolla systemctl status tai docker ps), palomuuri estää portin (testaa komennolla telnet host port), käytät väärää porttia (esim. 80 eikä 443, tai 8080 kehityspalvelimelle), tai palvelimen kuuntelujono on täynnä suuren kuorman alla. Vianmääritykseen: käytä curl -v URL ja etsi tulosteesta "Connected to" tai "Connection refused".