| Message ID | 20210227191813.96148-4-sandals@crustytoothpaste.net (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | Documentation updates to FAQ and git-archive | expand |
On Sat, Feb 27 2021, brian m. carlson wrote: > There are a lot of questions on the Internet about common problems with > fetching and pushing. Roughly, the vast majority of these problems are > when using HTTP and involve HTTP/2 streams, certain HTTP errors, or > connections which are interrupted. This latter case is especially > common on Windows where non-default antivirus and firewall software > frequently tampers with connections in undesirable ways. > > Let's add some FAQ entries explaining what is happening and how to > troubleshoot and solve these problems. When discussing network > connection issues, explicitly call out TLS man-in-the-middle devices, > proxies, antivirus programs, and firewall applications, which are the > cause of most of these problems, and encourage users to report these > programs as broken. Since many sites offer both HTTPS and SSH, suggest > using SSH, which is often not intercepted, as a good way to work around > these problems. > > Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net> > --- > Documentation/gitfaq.txt | 100 +++++++++++++++++++++++++++++++++++++++ > 1 file changed, 100 insertions(+) > > diff --git a/Documentation/gitfaq.txt b/Documentation/gitfaq.txt > index a132f66032..fde54d2664 100644 > --- a/Documentation/gitfaq.txt > +++ b/Documentation/gitfaq.txt > @@ -185,6 +185,106 @@ Then, you can adjust your push URL to use `git@example_author` or > `git@example_committer` instead of `git@example.org` (e.g., `git remote set-url > git@example_author:org1/project1.git`). > > +Problems Fetching and Pushing > +----------------------------- > + > +[[remote-connection-http-2-stream-error]] > +Why do I get an error about an HTTP/2 stream not being closed cleanly?:: > + Sometimes when pushing or fetching over HTTP, users see a message such as "RPC > + failed; curl 92 HTTP/2 stream 0 was not closed cleanly". This message > + indicates that Git is using HTTP/2, a recent version of the HTTP protocol, and > + that the remote server, or a middlebox, such as a proxy, TLS middlebox, > + antivirus, or firewall, failed to speak the protocol correctly and thus the > + connection was interrupted. > ++ > +In such a case, the software causing the problem is buggy and will likely be > +broken with a wide variety of web browsers and other HTTP-using applications. > +The best thing to do is contact the responsible party to get the software fixed. > ++ > +If that isn't possible, you can set the `http.version` option to `HTTP/1.1`, > +which will force the use of an older version of HTTP. This should allow Git to > +function with this broken software or device. If the remote server supports > +SSH, you may wish to try switching to SSH instead. > + > +[[remote-connection-http-411]] > +Why do I get an error about an HTTP 411 status?:: > + Sometimes users see error messages when pushing that refer to HTTP status 411, > + such as "RPC failed; result=22, HTTP code = 411." This status means that the > + server or a machine in the middle, such as a proxy, TLS middlebox, antivirus, > + firewall, or other middlebox, refuses to accept a streaming data connection. > ++ > +When pushing or fetching over HTTP, Git normally uses a small buffer and, if the > +data is large, uses HTTP 1.1 chunked transfer encoding or HTTP 2 streaming to > +send the data without a defined size. This is useful because it allows a push > +or fetch to start much faster and therefore complete much faster. This type of > +streaming has been standardized since 1999 and is well understood, and all > +modern software should be capable of supporting it. > ++ > +However, in this case, the remote server or middlebox is misconfigured and does > +not correctly support this. The best thing to do is contact the responsible > +party and ask them to fix the server or middlebox, since this misconfiguration > +can affect many pieces of software, some of which will simply not function at > +all in this environment. > ++ > +If the remote server supports SSH, you may wish to try using SSH instead. If > +that is not possible, you can set `http.postBuffer` to a larger value as a > +workaround. This is one of the few times when that option is useful, but note > +<<http-postbuffer,as outlined in the answer above>> that doing so will increase > +the memory usage for every push, no matter how small, and will not be able to > +handle pushes of arbitrary sizes, so fixing the broken server or device or > +switching to SSH is preferable in almost all cases. > + > +[[remote-connection-reset]] > +Why do I get errors that the connection was reset?:: > + When pushing or fetching, sometimes users see problems where the connection > + was reset. Common symptoms of this problem include (but are not limited to) > + messages like the following: > ++ > +* RPC failed; curl 56 OpenSSL SSL_read: Connection was reset, errno 10054 > +* RPC failed; curl 55 SSL_write() returned SYSCALL, errno = 10053 > +* RPC failed; curl 56 LibreSSL SSL_read: SSL_ERROR_SYSCALL, errno 60 > +* RPC failed; result=56, HTTP code = 200 > +* RPC failed; curl 56 GnuTLS recv error (-110): The TLS connection was non-properly terminated. I haven't looked in details at the content of the FAQ itself being added here (as far as proposed solutions etc. go), but I wonder if this wouldn't be 10x more useful to users if we cross-linked these errors with the docs, e.g.: diff --git a/remote-curl.c b/remote-curl.c index 0290b04891..ffb1001703 100644 --- a/remote-curl.c +++ b/remote-curl.c @@ -829,7 +829,7 @@ static int run_slot(struct active_request_slot *slot, strbuf_addstr(&msg, curl_errorstr); } } - error(_("RPC failed; %s"), msg.buf); + error(_("RPC failed (see 'git help faq'); %s"), msg.buf); strbuf_release(&msg); } > +These messages, and almost every message with a libcurl error code of 55 or 56, > +essentially mean that the network connection between Git and the remote server > +was terminated unexpectedly. This can be caused by any sort of generic network > +problem, such as packet loss or an unstable connection. Sometimes users also > +see it when connected to a VPN if the connection over the VPN is unstable. In > +such a case, disabling the VPN or switching to a different connection may help > +the problem, or sending or receiving less data may work around the problem. > ++ > +This may also be caused by devices or software in the middle of the connection > +which attempt to inspect the data. For example, if you're on a network which > +uses a TLS middlebox or a proxy, these devices may attempt to inspect the data > +and terminate the connection if the data is too large for them to handle or if > +they mistakenly think it is malicious, offensive, inappropriate, or otherwise > +unacceptable. To test if this is the problem, try using a different network > +where these devices are not enabled, or contact your network administrator and > +report the problem to them. > ++ > +On Windows, and to a lesser extent on other platforms, antivirus, firewall, or > +network monitoring software that is not the default (on Windows, something other > +than Windows Defender and Windows Firewall) can intercept network connections > +and cause the same problems as the devices mentioned above. This may also > +happen when using Git under the Windows Subsystem for Linux with such software. > +To test if this is the problem, remove the non-default software completely and > +restart your computer. Some such software does not disable the broken > +functionality properly when it is set to disabled and so removing the software > +is the only way to perform the test. If this is the problem, use the default > +software instead, report the problem to the software vendor, or contact your > +network administrator and report the problem to them. > ++ > +If you are using HTTPS and the remote server supports SSH, you may wish to try > +using SSH instead. > ++ > +Note that in all these cases, this is not a problem in Git, but a problem with > +the network or the devices and software managing it. Some parties mistakenly > +recommend adjusting the `http.postBuffer` setting to work around this, but > +<<http-postbuffer,see the above answer>> for why that usually doesn't work, and > +even when it does work, indicates a defect in the network or software such as > +one mentioned above in this answer. > + > Common Issues > ------------- >
On 2021-02-28 at 12:37:39, Ævar Arnfjörð Bjarmason wrote: > I haven't looked in details at the content of the FAQ itself being added > here (as far as proposed solutions etc. go), but I wonder if this > wouldn't be 10x more useful to users if we cross-linked these errors > with the docs, e.g.: > > diff --git a/remote-curl.c b/remote-curl.c > index 0290b04891..ffb1001703 100644 > --- a/remote-curl.c > +++ b/remote-curl.c > @@ -829,7 +829,7 @@ static int run_slot(struct active_request_slot *slot, > strbuf_addstr(&msg, curl_errorstr); > } > } > - error(_("RPC failed; %s"), msg.buf); > + error(_("RPC failed (see 'git help faq'); %s"), msg.buf); > strbuf_release(&msg); > } Sure, I can send a patch to do that. That's a great idea.
"brian m. carlson" <sandals@crustytoothpaste.net> writes: > +[[remote-connection-http-411]] > +Why do I get an error about an HTTP 411 status?:: > + Sometimes users see error messages when pushing that refer to HTTP status 411, > + such as "RPC failed; result=22, HTTP code = 411." This status means that the > + server or a machine in the middle, such as a proxy, TLS middlebox, antivirus, > + firewall, or other middlebox, refuses to accept a streaming data connection. > ++ > +When pushing or fetching over HTTP, Git normally uses a small buffer and, if the > +data is large, uses HTTP 1.1 chunked transfer encoding or HTTP 2 streaming to > +send the data without a defined size. This is useful because it allows a push > +or fetch to start much faster and therefore complete much faster. This type of > +streaming has been standardized since 1999 and is well understood, and all > +modern software should be capable of supporting it. > ++ > +However, in this case, the remote server or middlebox is misconfigured and does > +not correctly support this. The best thing to do is contact the responsible > +party and ask them to fix the server or middlebox, since this misconfiguration > +can affect many pieces of software, some of which will simply not function at > +all in this environment. > ++ > +If the remote server supports SSH, you may wish to try using SSH instead. If > +that is not possible, you can set `http.postBuffer` to a larger value as a > +workaround. This is one of the few times when that option is useful, but note > +<<http-postbuffer,as outlined in the answer above>> that doing so will increase > +the memory usage for every push, no matter how small, and will not be able to > +handle pushes of arbitrary sizes, so fixing the broken server or device or > +switching to SSH is preferable in almost all cases. Don't we rather want to merge this with [[http-postbuffer] part of the faq? If we can have two header lines for the same description (i.e. the FAQ list may have "What does `http.postBuffer` do?" aka "I got HTTP 411--what now?" as either a single link or a two separate but clearly related entries), that might be ideal. Thanks.
diff --git a/Documentation/gitfaq.txt b/Documentation/gitfaq.txt index a132f66032..fde54d2664 100644 --- a/Documentation/gitfaq.txt +++ b/Documentation/gitfaq.txt @@ -185,6 +185,106 @@ Then, you can adjust your push URL to use `git@example_author` or `git@example_committer` instead of `git@example.org` (e.g., `git remote set-url git@example_author:org1/project1.git`). +Problems Fetching and Pushing +----------------------------- + +[[remote-connection-http-2-stream-error]] +Why do I get an error about an HTTP/2 stream not being closed cleanly?:: + Sometimes when pushing or fetching over HTTP, users see a message such as "RPC + failed; curl 92 HTTP/2 stream 0 was not closed cleanly". This message + indicates that Git is using HTTP/2, a recent version of the HTTP protocol, and + that the remote server, or a middlebox, such as a proxy, TLS middlebox, + antivirus, or firewall, failed to speak the protocol correctly and thus the + connection was interrupted. ++ +In such a case, the software causing the problem is buggy and will likely be +broken with a wide variety of web browsers and other HTTP-using applications. +The best thing to do is contact the responsible party to get the software fixed. ++ +If that isn't possible, you can set the `http.version` option to `HTTP/1.1`, +which will force the use of an older version of HTTP. This should allow Git to +function with this broken software or device. If the remote server supports +SSH, you may wish to try switching to SSH instead. + +[[remote-connection-http-411]] +Why do I get an error about an HTTP 411 status?:: + Sometimes users see error messages when pushing that refer to HTTP status 411, + such as "RPC failed; result=22, HTTP code = 411." This status means that the + server or a machine in the middle, such as a proxy, TLS middlebox, antivirus, + firewall, or other middlebox, refuses to accept a streaming data connection. ++ +When pushing or fetching over HTTP, Git normally uses a small buffer and, if the +data is large, uses HTTP 1.1 chunked transfer encoding or HTTP 2 streaming to +send the data without a defined size. This is useful because it allows a push +or fetch to start much faster and therefore complete much faster. This type of +streaming has been standardized since 1999 and is well understood, and all +modern software should be capable of supporting it. ++ +However, in this case, the remote server or middlebox is misconfigured and does +not correctly support this. The best thing to do is contact the responsible +party and ask them to fix the server or middlebox, since this misconfiguration +can affect many pieces of software, some of which will simply not function at +all in this environment. ++ +If the remote server supports SSH, you may wish to try using SSH instead. If +that is not possible, you can set `http.postBuffer` to a larger value as a +workaround. This is one of the few times when that option is useful, but note +<<http-postbuffer,as outlined in the answer above>> that doing so will increase +the memory usage for every push, no matter how small, and will not be able to +handle pushes of arbitrary sizes, so fixing the broken server or device or +switching to SSH is preferable in almost all cases. + +[[remote-connection-reset]] +Why do I get errors that the connection was reset?:: + When pushing or fetching, sometimes users see problems where the connection + was reset. Common symptoms of this problem include (but are not limited to) + messages like the following: ++ +* RPC failed; curl 56 OpenSSL SSL_read: Connection was reset, errno 10054 +* RPC failed; curl 55 SSL_write() returned SYSCALL, errno = 10053 +* RPC failed; curl 56 LibreSSL SSL_read: SSL_ERROR_SYSCALL, errno 60 +* RPC failed; result=56, HTTP code = 200 +* RPC failed; curl 56 GnuTLS recv error (-110): The TLS connection was non-properly terminated. ++ +These messages, and almost every message with a libcurl error code of 55 or 56, +essentially mean that the network connection between Git and the remote server +was terminated unexpectedly. This can be caused by any sort of generic network +problem, such as packet loss or an unstable connection. Sometimes users also +see it when connected to a VPN if the connection over the VPN is unstable. In +such a case, disabling the VPN or switching to a different connection may help +the problem, or sending or receiving less data may work around the problem. ++ +This may also be caused by devices or software in the middle of the connection +which attempt to inspect the data. For example, if you're on a network which +uses a TLS middlebox or a proxy, these devices may attempt to inspect the data +and terminate the connection if the data is too large for them to handle or if +they mistakenly think it is malicious, offensive, inappropriate, or otherwise +unacceptable. To test if this is the problem, try using a different network +where these devices are not enabled, or contact your network administrator and +report the problem to them. ++ +On Windows, and to a lesser extent on other platforms, antivirus, firewall, or +network monitoring software that is not the default (on Windows, something other +than Windows Defender and Windows Firewall) can intercept network connections +and cause the same problems as the devices mentioned above. This may also +happen when using Git under the Windows Subsystem for Linux with such software. +To test if this is the problem, remove the non-default software completely and +restart your computer. Some such software does not disable the broken +functionality properly when it is set to disabled and so removing the software +is the only way to perform the test. If this is the problem, use the default +software instead, report the problem to the software vendor, or contact your +network administrator and report the problem to them. ++ +If you are using HTTPS and the remote server supports SSH, you may wish to try +using SSH instead. ++ +Note that in all these cases, this is not a problem in Git, but a problem with +the network or the devices and software managing it. Some parties mistakenly +recommend adjusting the `http.postBuffer` setting to work around this, but +<<http-postbuffer,see the above answer>> for why that usually doesn't work, and +even when it does work, indicates a defect in the network or software such as +one mentioned above in this answer. + Common Issues -------------
There are a lot of questions on the Internet about common problems with fetching and pushing. Roughly, the vast majority of these problems are when using HTTP and involve HTTP/2 streams, certain HTTP errors, or connections which are interrupted. This latter case is especially common on Windows where non-default antivirus and firewall software frequently tampers with connections in undesirable ways. Let's add some FAQ entries explaining what is happening and how to troubleshoot and solve these problems. When discussing network connection issues, explicitly call out TLS man-in-the-middle devices, proxies, antivirus programs, and firewall applications, which are the cause of most of these problems, and encourage users to report these programs as broken. Since many sites offer both HTTPS and SSH, suggest using SSH, which is often not intercepted, as a good way to work around these problems. Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net> --- Documentation/gitfaq.txt | 100 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 100 insertions(+)