Docs: Add Upgrade Fix to Troubleshooting (NVIDIA#659)

* Introduce additional troubleshooting information due to in-place upgrade from aiq -> nat modules
* Restructure Troubleshooting page based on type

Closes

## By Submitting this PR I confirm:
- I am familiar with the [Contributing Guidelines](https://github.com/NVIDIA/NeMo-Agent-Toolkit/blob/develop/docs/source/resources/contributing.md).
- We require that all contributors "sign-off" on their commits. This certifies that the contribution is your original work, or you have rights to submit it under the same license, or a compatible license.
  - Any contribution which contains commits that are not Signed-Off will not be accepted.
- When the PR is ready for review, new or existing tests cover these changes.
- When the PR is ready for review, the documentation is up to date with these changes.

Authors:
  - Will Killian (https://github.com/willkill07)

Approvers:
  - David Gardner (https://github.com/dagardner-nv)

URL: NVIDIA#659
Signed-off-by: Sangharsh Aglave <[email protected]>

Author: willkill07

docs/source/troubleshooting.md

@@ -17,12 +17,33 @@ limitations under the License.
 
 # NVIDIA NeMo Agent Toolkit Troubleshooting
 
-If you encounter any issues:
+## Workflow Issues
 
 - **Workflow Not Found**: Ensure that your workflow is correctly registered and that the `_type` in your configuration file matches the workflow's `_type`.
 
-- **Dependency Issues**: Verify that all required dependencies are listed in your `pyproject.toml` file and installed. If in doubt run `uv sync --all-groups --all-extras` from the root of the repository.
-
-- **Environment Variables**: Double-check that your `NVIDIA_API_KEY` is correctly set.
+- **Requested {category} type is ambiguous**: This error might arise when the `_type` in your configuration file is not unique. Please ensure that the `_type` is unique for each workflow. It can also occur after upgrading the toolkit from a previous version in-place when developing. To fix this issue, run the following commands:
+
+    <!-- path-check-skip-begin -->
+    ```bash
+    # Remove all __pycache__ directories -- the existing __pycache__ directories contain the old aiqtoolkit packages
+    find . -name __pycache__ -type d -exec rm -rf {} +
+    # Remove references to the old aiqtoolkit packages
+    rm -rf packages/aiqtoolkit*
+    # Remove references to the old aiq tests
+    rm -rf tests/aiq
+    # Remove the current environment since we are going to recreate it
+    deactivate; rm -rf .venv
+    # Reinstall the environment
+    uv sync --all-groups --all-extras
+    ```
+    <!-- path-check-skip-end -->
+
+## Runtime Issues
 
 - **[429] Too Many Requests**: This error might arise during executing workflows that involve LLM calls because of rate limiting on the LLM models. It is recommended to pause briefly and then attempt the operation again a few times. For warm fix set the `parse_agent_response_max_retries: 1` in `config.yaml` for the `react_agent`. Usually happens that the `react_agent` exhausts the available LLM rate with entire error stack trace.
+
+- **Environment Variables**: Double-check that your `NVIDIA_API_KEY` is correctly set if using NVIDIA NIMs. For other LLM providers, you may need to set other environment variables.
+
+## Dependency Issues
+
+- **Requested type not found**: Verify that all required dependencies are listed in your `pyproject.toml` file and installed. If in doubt run `uv sync --all-groups --all-extras` from the root of the repository.