Troubleshooting

Real error messages this template's own scripts have hit, and the exact fix. If your error is not here, read the [ERROR] ... line the script printed - every failure point in 6-build-and-test-*, 7-build-all-* and 10-release-* prints a specific fix, not just "something went wrong".

Error message (or symptom)	Cause	Fix
'7-build-all-windows.bat' is not recognized as an internal or external command (when calling one script from another, or from a shell prompt without typing the leading .\/\)	Some machines set NoDefaultCurrentDirectoryInExePath=1, which stops both cmd.exe and PowerShell from searching the current folder for a bare filename.	Always invoke a script with an explicit path: .\7-build-all-windows.bat in PowerShell, call .\7-build-all-windows.bat from inside another .bat (this is what 10-release-windows.bat does).
*.jar: Cannot stat: No such file or directory from tar	cmd.exe does not expand *.jar, so tar receives the literal string '*.jar' as a filename.	Name the file explicitly (tar ... -C calculator-app\target calculator-app-1.1.0.jar). assemble.py packs everything with Python, so the scripts never hit this; you only meet it in your own tar commands.
The system cannot find the file specified. printed by rd /S /Q	rd on a folder that does not exist yet (e.g. the very first run, before any report has been generated) errors instead of silently doing nothing.	Guard it: if exist "folder" rd /S /Q "folder". On Linux, rm -rf has no such problem - a missing path is a silent no-op.
genhtml: ERROR: no valid records found in tracefile ...\lcov.info and the file is 0 bytes	The --prefix argument to coverxygen was quoted as "...\calculator-app\" - a trailing backslash immediately before the closing double-quote. Windows' argument parser treats \" as an escaped literal quote, not a closing quote, so it silently swallows every argument after it and coverxygen runs with no source directory, producing an empty file.	Never end a quoted Windows command-line argument with a backslash. Use a forward slash instead ("...\calculator-app/" is fine), or use %VAR:\=/% to convert backslashes to forward slashes first (what 7-build-all-windows.bat does), or simply do not quote the argument if it has no spaces.
Can't open perl script "genhtml": No such file or directory	genhtml from a Chocolatey lcov install has no .exe extension - it is a Perl script. cmd.exe's where genhtml reports it found something, but running the bare word genhtml does not work; you must resolve the actual path and run perl "<path>".	7-build-all-windows.bat captures the resolved path from where genhtml and calls perl "<that path>" ... explicitly. On Linux, genhtml is a normal, directly-executable command - no Perl wrapper needed.
Documentation-coverage report is silently empty; coverxygen produces nothing and prints nothing obviously wrong	Plain python on PATH resolved to an unrelated install (e.g. a graphics application's bundled Python 2.7) that does not have the coverxygen package, so python -m coverxygen fails to find the module and the script did not check for that.	Call a specific, known-good interpreter: py -3.12 -m coverxygen ... (the py launcher picks the exact version you ask for, regardless of what python happens to point at). 7-build-all-windows.bat checks py -3.12 -c "import coverxygen" first and prints an actionable error if it is missing, instead of silently producing nothing.
where python shows a Python you did not expect (Inkscape, GIMP, an old 2.7, ...)	Several non-development applications ship their own bundled Python and add it to PATH, often ahead of your real install.	Do not rely on bare python/pip in scripts or in your own tooling. Use py -3.12 (the Python Launcher for Windows) which is unambiguous, or check where python and reorder PATH if you need bare python to work for interactive use.
mvn fails with a message about requireJavaVersion / requireMavenVersion from maven-enforcer-plugin	Your JAVA_HOME/PATH points at a JDK older than 17, or your Maven is older than 3.8.	Install/point at JDK 17+ (java -version should show 17 or higher) and Maven 3.8+ (mvn -version). This project's pom.xml enforces this on purpose so you get this clear message instead of a confusing compile error deep in the build.
mvn site fails on the "Test Javadoc" report: error: No public or protected classes found to document	maven-javadoc-plugin's default report set also tries to Javadoc the test sources; this template's test classes are intentionally package-private (plain JUnit 5 style), so there is nothing public to document.	Already fixed in pom.xml: the <reportSets> for maven-javadoc-plugin only requests the main-source javadoc report, not test-javadoc. If you add your own reporting plugins, watch for the same "no public members" failure on test sources.
maven-shade-plugin warns Discovered module-info.class. Shading will break its strong encapsulation.	logback-classic/logback-core (1.6.x) ship a module-info.class; shading (merging many jars into one) is incompatible with that module descriptor.	Already fixed in pom.xml: a shade <filter> excludes module-info.class from the uber jar. The overlapping resource: META-INF/MANIFEST.MF warning that remains is normal shade-plugin behavior (every jar has a manifest) and is harmless.
A desktop.ini file keeps reappearing / shows up in git status	This repository lives inside Google Drive for Desktop, which drops a hidden desktop.ini into every folder it manages.	Run scripts\delete-desktop-ini-windows.bat / scripts/delete-desktop-ini-linux.sh (the pre-commit and pre-push hooks do it too). It is already in .gitignore, but Drive can recreate the file after it is deleted from the index.
Paths longer than 260 characters fail on Windows (git, mvn, or a plugin complains)	Windows' classic MAX_PATH limit, combined with a deep Maven/Doxygen/JaCoCo output tree plus a long Google Drive path.	git config --system core.longpaths true (the CI workflow already does the Actions-runner equivalent); on Windows 10/11, also enable long paths in Group Policy/registry (LongPathsEnabled) if you still hit it outside git. Building in a shorter path (e.g. %TEMP%\tmpl-run\<repo> instead of deep inside Google Drive) avoids it entirely - see the note in install.md about Drive.
A build step fails with a file "in use by another process", or writes silently do not take effect	Antivirus or Google Drive for Desktop is holding a lock on a file under target/ or is re-syncing it mid-build.	Re-run the script (these are almost always transient); if it persists, build in a local, non-synced folder (%TEMP%\tmpl-run\<repo> / ~/tmpl-run/<repo>) instead of directly inside the Google Drive folder, and add an antivirus exclusion for your build/output folders if your policy allows it.
WSL cannot see G:\... / your Google Drive path is not visible from an Ubuntu/WSL terminal	WSL2 does not automatically mount arbitrary mapped/virtual drives the way it mounts real local disks (/mnt/c, /mnt/g only works for a real local G: drive, not Google Drive's virtual filesystem).	Copy the repo to a local folder first: from PowerShell, robocopy "G:\...\eclipse-java-maven-template" "$env:TEMP\tmpl-run\eclipse-java-maven-template" /E; then from WSL, cp -r "/mnt/c/Users/<you>/AppData/Local/Temp/tmpl-run/eclipse-java-maven-template" ~/tmpl-run/ and build there. Do the same for any script you want to test from WSL.
mvn site prints Site model ... is still using the old pre-version 2.0.0 model. You MUST migrate ...	Informational warning from maven-site-plugin about a future decoration-model change coming in the (still-beta, as of this writing) 4.x line of the plugin.	Safe to ignore while pinned to the stable maven-site-plugin 3.x line (this project uses 3.22.0 on purpose, not the 4.0.0 beta). Re-check when 4.x reaches a stable release.
Address already in use / OSError: [Errno 98] when running 9-open-site-*	Another server (an earlier 9-open-site, or mkdocs serve) still listens on the port.	Close the old terminal, or pick another port: 9-open-site-windows.bat 8080 / ./9-open-site-linux.sh 8080.
9-open-site-* says it cannot find Python	No Python 3 on PATH, or only the wrong one.	Install Python 3.12 (see install.md); scripts/detect-python-* tries py -3.12, py -3.13, ... and python3.
A report page's <iframe> stays blank when opened via file://	Most browsers refuse to load a framed page from file://.	Always open the site with 9-open-site-* (an http://localhost:8000/ URL), never by double-clicking index.html.
reportgenerator fails with A fatal error occurred. The required library ... could not be found / You must install .NET to run this application / it names a missing framework version even though the right SDK is installed (Linux/WSL)	reportgenerator is a .NET "apphost" executable; it resolves its runtime through the DOTNET_ROOT environment variable, not just PATH. A machine with more than one .NET SDK (e.g. an old pre-installed 3.1 alongside a newer per-user install under $HOME/.dotnet) can have dotnet on PATH pointing at the right place while the apphost still resolves the wrong - or no - runtime without DOTNET_ROOT.	export DOTNET_ROOT="$HOME/.dotnet" (alongside the PATH export) - 4-install-tools-linux.sh prints this exact line after installing the SDK.
dotnet tool update --global dotnet-reportgenerator-globaltool fails with error NU1202: Package ... is not compatible with netcoreapp3.1	The active dotnet is an old SDK (e.g. 3.1) that cannot restore a tool package targeting a newer framework (ReportGenerator 5.5+ targets net8.0/9.0/10.0).	Install/switch to a .NET SDK 8+ first (4-install-tools-linux.sh checks for this specifically and installs one per-user if needed), then re-run the tool install/update.
A .sh script fails with bad interpreter: /bin/bash^M: no such file or directory, or bash -n script.sh reports unexpected end of file for a script that looks fine	The file has CRLF line endings (a \r before every \n) - common after editing on Windows, or if it was ever checked out with core.autocrlf=true before this repo's .gitattributes existed. A \r right before the shebang's newline, or right before a closing done/fi, can make bash misparse the file.	This repo's .gitattributes forces *.sh (and pre-commit/pre-push) to LF on checkout, so a fresh git clone is unaffected. If you still hit this (e.g. you copied files by hand instead of cloning), reconvert the file: sed -i 's/\r$//' script.sh on Linux/WSL, or open it in an editor set to LF line endings on Windows.
gh release create fails with 403/404, or 10-release-* stops at "gh is not logged in"	not authenticated, wrong account, or no write access	See releases.md.
'6-build-and-test-windows.bat' is not recognized when one script calls another	see the first row: the current folder is not searched	scripts call each other as call .\6-build-and-test-windows.bat; call yours the same way
mkdocs build --strict fails with A reference to 'guide/xyz.md' is included in the 'nav' configuration, which is not found	a page listed in nav: of mkdocs.yml does not exist (typo, or a generated report page - assemble.py site was not run)	run py -3.12 scripts/assemble.py site first (7-build-all-* does), or fix the path in nav:
No module named material / No module named junit2htmlreport / No module named coverxygen	the Python that runs the scripts is not the one you installed the packages into	py -3.12 -m pip install --user -r requirements.txt (Windows) or python3 -m pip install --user -r requirements.txt (Linux); 4-install-tools-* does it
error: externally-managed-environment when installing the Python packages on new Ubuntu/Debian	PEP 668: the system Python refuses pip install --user	python3 -m pip install --user --break-system-packages -r requirements.txt (what 4-install-tools-linux.sh falls back to) or use a virtual environment
mvn builds but the jar is called calculator-app-1.0-SNAPSHOT.jar and scripts cannot find calculator-app-1.1.0.jar	Maven was started without -Drevision, e.g. from Eclipse, and the pom.xml default differs from project.env	build through the scripts (they pass -Drevision=<VERSION>) or keep <revision> in pom.xml equal to VERSION in project.env
reports/<platform>/... folders exist but a report page in the site says Not available in this build	that report (or the whole platform) was not built on this machine	run 7-build-all-<platform> for that platform; in CI both are built and merged
CI: check-links reports [BROKEN] ...	a link inside one of OUR site pages points to a missing file (third-party report folders only produce warnings)	fix the link in the Markdown file named in the message and rebuild