Add note about gclient sync network failures and workaround (#183794)

ashoknarayan · gemini-code-assist[bot] · web-flow · commit dc153bcf48ed · 2026-03-23T18:48:09.000Z
Adds a note to the engine setup guide about potential network-related failures during `gclient sync` and suggests using `--no-history` as a workaround. Fixes #141087 ## Pre-launch Checklist - [X] I read the [Contributor Guide] and followed the process outlined there for submitting PRs. - [X] I read the [AI contribution guidelines] and understand my responsibilities, or I am not using AI tools. - [X] I read the [Tree Hygiene] wiki page, which explains my responsibilities. - [X] I read and followed the [Flutter Style Guide], including [Features we expect every widget to implement]. - [X] I signed the [CLA]. - [X] I listed at least one issue that this PR fixes in the description above. - [X] I updated/added relevant documentation (doc comments with `///`). - [X] I added new tests to check the change I am making, or this PR is [test-exempt]. - [X] I followed the [breaking change policy] and added [Data Driven Fixes] where supported. - [X] All existing and new tests are passing.  [Contributor Guide]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#overview [AI contribution guidelines]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#ai-contribution-guidelines [Tree Hygiene]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md [test-exempt]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#tests [Flutter Style Guide]: https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md [Features we expect every widget to implement]: https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md#features-we-expect-every-widget-to-implement [CLA]: https://cla.developers.google.com/ [flutter/tests]: https://github.com/flutter/tests [breaking change policy]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#handling-breaking-changes [Discord]: https://github.com/flutter/flutter/blob/main/docs/contributing/Chat.md [Data Driven Fixes]: https://github.com/flutter/flutter/blob/main/docs/contributing/Data-driven-Fixes.md --------- Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
diff --git a/docs/engine/contributing/Setting-up-the-Engine-development-environment.md b/docs/engine/contributing/Setting-up-the-Engine-development-environment.md
@@ -57,6 +57,27 @@ Flutter engine uses `gclient` to manage dependencies.
     2. Everyone else: copy `standard.gclient`
 2. Run `gclient sync` from the root folder
 
+> [!NOTE]
+> If `gclient sync` fails with errors such as:
+>
+> ```
+> fatal: early EOF
+> fatal: the remote end hung up unexpectedly
+> error: RPC failed; curl 18 transfer closed with outstanding read data remaining
+> ```
+>
+> This is often caused by network instability during large repository fetches.
+>
+> As a workaround, you can run:
+>
+> ```
+> gclient sync --no-history
+> ```
+>
+> This performs a shallow sync, reducing download size and improving reliability.
+>
+> Note that this omits full Git history, which may limit certain development workflows.
+
 ### Add `et` to `PATH`
 
 The "Engine Tool" called `et` is useful when working with the engine. It is located in the [`flutter/engine/src/flutter/bin`](https://github.com/flutter/flutter/tree/0c3359df8c8342c8907316488b1404a216f215b6/engine/src/flutter/bin) directory. Add this to your `$PATH` in your `.rc` file: e.g. on UNIX, using `export PATH=/path/to/flutter/engine/src/flutter/bin:$PATH`.
