====== 6.6 Troubleshooting Tool Issues ======

[[fxdemo:05-part:start | Go To Top ]]

[[fxdemo:05-part:06-prerequisites-and-tooling:start | Return to Prerequisites and Tooling ]]

The handbook should help developers resolve common tooling problems without turning every setup issue into an architecture discussion.

Troubleshooting guidance should cover predictable failures such as:

  - Git cannot access the [[dido:99_annexes:annex-b-terms-and-definitions:r:repository|Repository]].
  - The shell cannot execute a script.
  - A script has incorrect line endings or permissions.
  - Python points to the wrong interpreter.
  - The virtual environment does not exist or contains missing packages.
  - [[dido:99_annexes:annex-b-terms-and-definitions:d:dds|DDS]] environment variables are missing.
  - The [[dido:99_annexes:annex-b-terms-and-definitions:i:idl|IDL]] compiler cannot find an input file.
  - Generated types appear in the wrong location.
  - The container runtime cannot build or run an image.
  - A required port, volume, network, or runtime path conflicts with a local setting.
  - VS Code cannot find recommended extensions or workspace tasks.

Troubleshooting guidance should direct developers back to the controlled [[dido:99_annexes:annex-b-terms-and-definitions:b:baseline|Baseline]]. Developers should fix the environment or update the documented Baseline through review. They should not solve prerequisite problems by adding undocumented local workarounds that only work on one machine.

When a tool issue reveals a real gap in the handbook, scripts, Repository layout, or Baseline assumptions, the team should update the relevant material. A repeated troubleshooting problem usually signals that the Baseline needs clearer instructions, stronger validation, or a simpler toolchain.

----

<WRAP centeralign>

© 2026 Dido Solutions, Inc. and Jackrabbit Consulting, Inc.

</WRAP>