From eed1957f03224bf800191390244c39ff5bb362d1 Mon Sep 17 00:00:00 2001 From: Liwx Date: Thu, 30 Oct 2025 14:10:52 +0800 Subject: [PATCH] Add FAQ for docker pull error on Kylin OS (#3870) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Added instructions for resolving 'invalid tar header' error on Kylin OS with an ARM64 architecture on Atlas300I hardware during docker pull, including steps for offline loading of docker images. --- ### What this PR does / why we need it? The primary motivation for this PR is to address a critical `docker pull` failure that occurs on specific, yet important, enterprise environments. Specifically, when operating on **Kylin OS (麒麟操作系统) with an ARM64 architecture on Atlas300I hardware**, users frequently encounter an `archive/tar: invalid tar header` error, which completely blocks the setup process. This issue has been consistently reproduced, with multiple retries failing with the same error, confirming that it is a persistent environmental problem rather than a transient network issue. image This guide provides a robust, step-by-step workaround using an offline-loading method (`docker save` on a host machine and `docker load` on the target machine). This solution is crucial for enabling users on this platform to use vLLM. This contribution does not directly fix an existing issue number, but it proactively solves a significant environmental and usability problem for a growing user base. ### Does this PR introduce _any_ user-facing change? No.It does not alter any code, APIs, interfaces, or existing behavior of the vLLM project. ### How was this patch tested? The instructions and troubleshooting steps in this guide were validated through a real-world, end-to-end test case on the my hardware and OS. The testing process was as follows: 1. **Problem Reproduction**: An attempt was made to directly `docker pull` the `vllm-ascend:v0.10.0rc1-310p` image on a target machine running Kylin OS (ARM64). The `invalid tar header` failure was successfully and consistently reproduced, confirming the existence of the problem. 2. **Solution Implementation**: The workaround detailed in the guide was executed: * On a separate host machine (Ubuntu x86_64), the image was successfully pulled using the `--platform linux/arm64` flag. * The image was then saved to a `.tar` archive using `docker save`. * The `.tar` archive was transferred to the target Kylin OS machine. * The image was successfully loaded from the archive using `docker load -i ...`. 3. **End-to-End Validation**: After loading the image, the vLLM container was launched on the target machine following the instructions in the guide. Both online inference (via `curl` to the API server) and offline inference (via the Python script) were executed successfully, confirming that the entire workflow described in the document is accurate and effective. Since this is a documentation-only change based on a validated workflow, no new unit or integration tests were added to the codebase. - vLLM version: v0.11.0rc3 - vLLM main: https://github.com/vllm-project/vllm/commit/83f478bb19489b41e9d208b47b4bb5a95ac171ac --------- Signed-off-by: Liwx Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> --- docs/source/faqs.md | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/docs/source/faqs.md b/docs/source/faqs.md index fabf7555..f997eb9f 100644 --- a/docs/source/faqs.md +++ b/docs/source/faqs.md @@ -212,3 +212,30 @@ The current stream requirement calculation for size captures only accounts for m ### 19. How to install custom version of torch_npu? torch-npu will be overridden when installing vllm-ascend. If you need to install a specific version of torch-npu, you can manually install the specified version of torch-npu after vllm-ascend is installed. + +### 20. On certain systems (e.g., Kylin OS), `docker pull` may fail with an `invalid tar header` error + +On certain operating systems, such as Kylin OS , you may encounter an `invalid tar header` error during the `docker pull` process: + +```text +failed to register layer: ApplyLayer exit status 1 stdout: stderr: archive/tar: invalid tar header +``` + +This is often due to system compatibility issues. You can resolve this by using an offline loading method with a second machine. + +1. On a separate host machine (e.g., a standard Ubuntu server), pull the image for the target ARM64 architecture and package it into a `.tar` file. + + ```bash + export IMAGE_TAG=v0.10.0rc1-310p + export IMAGE_NAME="quay.io/ascend/vllm-ascend:${IMAGE_TAG}" + # If in China region, uncomment to use a mirror: + # export IMAGE_NAME="m.daocloud.io/quay.io/ascend/vllm-ascend:${IMAGE_TAG}" + + # Pull the image for the ARM64 platform and save it + docker pull --platform linux/arm64 "${IMAGE_NAME}" + docker save -o "vllm_ascend_${IMAGE_TAG}.tar" "${IMAGE_NAME}" + ``` + +2. Transfer the image archive + +Copy the `vllm_ascend_.tar` file (where `` is the image tag you used) to your target machine