[Windows 10 + WSL2] Compilation/Run Issues (Docker/Vue/SCons) with Solutions

[Bob-JIN]

Background

I encountered the following compilation/run issues when setting up SWE on Windows 10 + WSL2 (Ubuntu 22.04), and resolved them with the steps below. Sharing for reference and potential config improvements.

- OS: Windows 10 Pro + WSL2 (Ubuntu 22.04 LTS)
- Docker version (WSL): [V 29.1.5]
- SWE branch/commit: [master]
- Node.js version (WSL): [V 12.9.1]

---

Issue 1: Docker Credential Helper Exec Format Error During Compilation

Error Message

When compiling the project in the stellarium-web-engine/apps/web-frontend/ directory following the instructions in README.md, the compilation failed with:

ERROR: failed to build: failed to solve: error getting credentials - err: fork/exec /usr/bin/docker-credential-desktop.exe: exec format error, out: ``      
make: *** [Makefile:37: setup] Error 1

Root Cause

WSL runs a Linux environment and cannot directly execute Windows executable files (.exe). This error stems from incorrect configuration of the Docker credential helper in WSL (the config references a Windows .exe credential tool that Linux cannot run).

Solution

1. Edit the Docker configuration file in WSL:

   nano ~/.docker/config.json

2. Remove the reference to the .exe credential helper (delete the docker-credential-desktop.exe entry in the config file).

---

Issue 2: Docker Permission Denied in make setup

Error Message

During the make setup process, an error occurred at line 40 of /apps/web-frontend/Makefile:

make: docker: Permission denied
make: *** [Makefile:40: setup] Error 127

Root Cause

The error is triggered by the parameter-passing logic in the docker build command used in the Makefile:

docker build -t stellarium-web-dev --build-arg USER_UID=${USER_UID} --build-arg USER_GID=${USER_GID} .

Solution

Remove the passed --build-arg parameters (while this may cause unforeseen minor issues, it is sufficient for debugging and demonstration purposes):

docker build -t stellarium-web-dev . # --no-cache (optional: add to rebuild without cache)

---

Issue 3: "Unsupported Pickle Protocol: 4" When Running make js

Error Message

When executing make js in the project root directory or any make * commands in other directories, the following error is thrown:

stellarium unsupported pickle protocol: 4

Root Cause

The Makefile essentially invokes the SCons build tool. On the first compilation, SCons automatically generates a build signature database file (.sconsign.dblite in the root directory) that stores metadata like source files (C++/JS, etc.), dependent libraries, and compilation commands. This file enables incremental compilation (only modified files are recompiled to avoid redundant builds). However, incremental compilation does not explicitly restrict the use of Python 2.7, leading to Python 3-related operations and triggering the "unsupported pickle protocol" error.

Solution

Directly delete the incremental compilation database file in the root directory:

rm .sconsign.dblite

---

Issue 4: Vue Version Incompatibility in make dev

Error Message

Running make dev in the /apps/web-frontend/ directory results in a Vue version mismatch error:

Vue packages version mismatch:

- vue@3.0.0 (/app/node_modules/vue/index.js)
- vue-template-compiler@2.6.12 (/app/node_modules/vue-template-compiler/package.json)

Root Cause

The Vue version constraints in the /apps/web-frontend/package.json file are not properly restricted, leading to conflicting versions being installed.

Solution

Modify the Vue-related dependencies in package.json to enforce consistent versions:

"dependencies": {
  // Other dependencies...
  "vue": "^2.6.12"
},
"devDependencies": {
  // Other dev dependencies...
  "vue-template-compiler": "^2.6.12"
}

---

[gzotti]

Thank you for these notes. Any build documentation is helpful to get this project up and running locally. Given that numerous package updates (many of them even security related) are being pushed by their respective authors, it may be wise to finally update the used packages where possible to current versions as of 2026. However I am not really familiar with this project, so this would require help from @xalioth.