Troubleshooting and FAQ

Troubleshooting & FAQ

Splits README's Common errors / doctor / FAQ sections into a page users will actually search first.

Outline

Reading doctor output

• What [OK] / [WARN] / [FAIL] mean, and the resulting exit code
• What's checked (WSL2, interop, WSLC, config, architecture, Git)
• Why a Git problem is only a warning

Common errors

• WSLC not found (the auto lookup order; how to install/update)
• Docker Hub authentication (the wslc registry login guidance)
• Slow boot with a bind-mounted app directory (symptom, cause, pointer to Guides)
• CPU architecture mismatch (docker buildx imagetools inspect / buildx build --platform examples)

FAQ (reproduced from README, expanded)

• Which mode should I start with?
• Can I use dependencies: and compose: together?
• What's the difference between mode: compose and mode: compose-native?
• Why would I need compose-native if dependencies: already gives me sidecars?
• What happens to compose-native once wslc gets native Compose support?
• Is sync: required?
• How does wip actually fix the slow bind-mount boot problem?
• Is it safe to put passwords/secrets in wip.yml?
• wslc.exe/wslc isn't found — what do I do?
• Do I need to rename interaction: when migrating from dip?

Filing an issue for anything not covered here

• What to include (CONTRIBUTING.md link: your wip.yml, the exact command and output, WIP_DEBUG=1 output, wip doctor output, OS/WSL/WSLC versions)