# Troubleshooting

> Troubleshooting - Troubleshoot common issues when working with DataRobot Agent Templates.

This Markdown file sits beside the HTML page at the same path (with a `.md` suffix). It summarizes the topic and lists links for tools and LLM context.

Companion generated at `2026-04-24T16:03:56.227025+00:00` (UTC).

## Primary page

- [Troubleshooting](https://docs.datarobot.com/en/docs/agentic-ai/agentic-develop/agentic-troubleshooting.html): Full documentation for this topic (HTML).

## Sections on this page

- [Prerequisites and setup issues](https://docs.datarobot.com/en/docs/agentic-ai/agentic-develop/agentic-troubleshooting.html#prerequisites-and-setup-issues): In-page section heading.
- [Windows compatibility](https://docs.datarobot.com/en/docs/agentic-ai/agentic-develop/agentic-troubleshooting.html#windows-compatibility): In-page section heading.
- [Missing prerequisites](https://docs.datarobot.com/en/docs/agentic-ai/agentic-develop/agentic-troubleshooting.html#missing-prerequisites): In-page section heading.
- [Build tools missing](https://docs.datarobot.com/en/docs/agentic-ai/agentic-develop/agentic-troubleshooting.html#build-tools-missing): In-page section heading.
- [Environment configuration issues](https://docs.datarobot.com/en/docs/agentic-ai/agentic-develop/agentic-troubleshooting.html#environment-configuration-issues): In-page section heading.
- [Missing environment variables](https://docs.datarobot.com/en/docs/agentic-ai/agentic-develop/agentic-troubleshooting.html#missing-environment-variables): In-page section heading.
- [Invalid endpoint configuration](https://docs.datarobot.com/en/docs/agentic-ai/agentic-develop/agentic-troubleshooting.html#invalid-endpoint-configuration): In-page section heading.
- [Authentication issues](https://docs.datarobot.com/en/docs/agentic-ai/agentic-develop/agentic-troubleshooting.html#authentication-issues): In-page section heading.
- [API token authentication failed](https://docs.datarobot.com/en/docs/agentic-ai/agentic-develop/agentic-troubleshooting.html#api-token-authentication-failed): In-page section heading.
- [Authorization context not set](https://docs.datarobot.com/en/docs/agentic-ai/agentic-develop/agentic-troubleshooting.html#authorization-context-not-set): In-page section heading.
- [Deployment issues](https://docs.datarobot.com/en/docs/agentic-ai/agentic-develop/agentic-troubleshooting.html#deployment-issues): In-page section heading.
- [Pulumi login required](https://docs.datarobot.com/en/docs/agentic-ai/agentic-develop/agentic-troubleshooting.html#pulumi-login-required): In-page section heading.
- [Deployment ID not found](https://docs.datarobot.com/en/docs/agentic-ai/agentic-develop/agentic-troubleshooting.html#deployment-id-not-found): In-page section heading.
- [CLI and testing issues](https://docs.datarobot.com/en/docs/agentic-ai/agentic-develop/agentic-troubleshooting.html#cli-and-testing-issues): In-page section heading.
- [CLI command not found](https://docs.datarobot.com/en/docs/agentic-ai/agentic-develop/agentic-troubleshooting.html#cli-command-not-found): In-page section heading.
- [Local testing fails](https://docs.datarobot.com/en/docs/agentic-ai/agentic-develop/agentic-troubleshooting.html#local-testing-fails): In-page section heading.
- [Infrastructure issues](https://docs.datarobot.com/en/docs/agentic-ai/agentic-develop/agentic-troubleshooting.html#infrastructure-issues): In-page section heading.
- [Docker build fails](https://docs.datarobot.com/en/docs/agentic-ai/agentic-develop/agentic-troubleshooting.html#docker-build-fails): In-page section heading.
- [Pulumi state issues](https://docs.datarobot.com/en/docs/agentic-ai/agentic-develop/agentic-troubleshooting.html#pulumi-state-issues): In-page section heading.
- [Import issues in myagent.py](https://docs.datarobot.com/en/docs/agentic-ai/agentic-develop/agentic-troubleshooting.html#import-issues-in-myagent-py): In-page section heading.
- [LLM gateway issues](https://docs.datarobot.com/en/docs/agentic-ai/agentic-develop/agentic-troubleshooting.html#llm-gateway-issues): In-page section heading.
- [Model access error](https://docs.datarobot.com/en/docs/agentic-ai/agentic-develop/agentic-troubleshooting.html#model-access-error): In-page section heading.
- [LLM gateway configuration](https://docs.datarobot.com/en/docs/agentic-ai/agentic-develop/agentic-troubleshooting.html#llm-gateway-configuration): In-page section heading.
- [Non-gateway model deployment](https://docs.datarobot.com/en/docs/agentic-ai/agentic-develop/agentic-troubleshooting.html#non-gateway-model-deployment): In-page section heading.
- [Accessing request headers](https://docs.datarobot.com/en/docs/agentic-ai/agentic-develop/agentic-troubleshooting.html#accessing-request-headers): In-page section heading.
- [Extracting X-Untrusted-* headers](https://docs.datarobot.com/en/docs/agentic-ai/agentic-develop/agentic-troubleshooting.html#extracting-x-untrusted-headers): In-page section heading.
- [Common use cases](https://docs.datarobot.com/en/docs/agentic-ai/agentic-develop/agentic-troubleshooting.html#common-use-cases-for-headers): In-page section heading.
- [Important considerations](https://docs.datarobot.com/en/docs/agentic-ai/agentic-develop/agentic-troubleshooting.html#header-considerations): In-page section heading.
- [Debugging tips](https://docs.datarobot.com/en/docs/agentic-ai/agentic-develop/agentic-troubleshooting.html#debugging-tips): In-page section heading.
- [Enable verbose logging](https://docs.datarobot.com/en/docs/agentic-ai/agentic-develop/agentic-troubleshooting.html#enable-verbose-logging): In-page section heading.
- [Test authentication](https://docs.datarobot.com/en/docs/agentic-ai/agentic-develop/agentic-troubleshooting.html#test-authentication): In-page section heading.
- [Check environment variables](https://docs.datarobot.com/en/docs/agentic-ai/agentic-develop/agentic-troubleshooting.html#check-environment-variables): In-page section heading.
- [Log request headers for debugging](https://docs.datarobot.com/en/docs/agentic-ai/agentic-develop/agentic-troubleshooting.html#log-request-headers): In-page section heading.
- [Getting help](https://docs.datarobot.com/en/docs/agentic-ai/agentic-develop/agentic-troubleshooting.html#getting-help): In-page section heading.

## Related documentation

- [Agentic AI](https://docs.datarobot.com/en/docs/agentic-ai/index.html): Linked from this page.
- [Build](https://docs.datarobot.com/en/docs/agentic-ai/agentic-develop/index.html): Linked from this page.
- [prerequisites guide](https://docs.datarobot.com/en/docs/agentic-ai/agentic-develop/agentic-install.html): Linked from this page.
- [Getting started with the DataRobot CLI](https://docs.datarobot.com/en/docs/agentic-ai/cli/getting-started.html): Linked from this page.
- [CLI troubleshooting](https://docs.datarobot.com/en/docs/agentic-ai/cli/troubleshooting.html): Linked from this page.
- [LLM gateway](https://docs.datarobot.com/en/docs/reference/gen-ai-ref/llm-availability.html): Linked from this page.
- [Contact DataRobot](https://docs.datarobot.com/en/docs/get-started/troubleshooting/general-help.html): Linked from this page.

## Documentation content

# Troubleshooting

This guide helps you diagnose and resolve common issues when working with DataRobot Agent Templates.

## Prerequisites and setup issues

Common issues related to system requirements and initial setup for DataRobot Agent Templates.

### Windows compatibility

Issue: Windows is not supported for DataRobot Agent Templates.

Solution: Use macOS or Linux for development.

### Missing prerequisites

Issue: Required tools are not installed.

Solution: Install missing tools following the [prerequisites guide](https://docs.datarobot.com/en/docs/agentic-ai/agentic-develop/agentic-install.html).

### Build tools missing

Issue: Build tools are not available on your system.

Solution: Install Xcode Command Line Tools (macOS) or build-essential (Linux).

## Environment configuration issues

Problems with environment variables and DataRobot endpoint configuration.

### Missing environment variables

Issue: Required environment variables are not set.

Solution: Create `.env` file with `DATAROBOT_API_TOKEN` and `DATAROBOT_ENDPOINT`.

### Invalid endpoint configuration

Issue: Incorrect DataRobot endpoint configured.

Solution: Use correct endpoint for your region (cloud) or contact support (on-premise).

## Authentication issues

Issues related to API authentication and authorization context setup.

### API token authentication failed

Issue: API token is invalid or lacks proper permissions.

Solution: Verify API token is valid and has proper permissions.

### Authorization context not set

Issue: Authorization context is not initialized in your agent.

Solution: Ensure `initialize_authorization_context()` is called in your agent.

## Deployment issues

Problems encountered during the deployment process and infrastructure management.

### Pulumi login required

Issue: Pulumi authentication is not configured.

Solution: Run `pulumi login --local` or `pulumi login`.

### Deployment ID not found

Issue: Cannot locate deployment ID after deployment.

Solution: Check terminal output or DataRobot UI → Console → Deployments.

## CLI and testing issues

Issues with command-line interface usage and local testing of agents.

### CLI command not found

Issue: CLI commands are not available.

Solution: Ensure the DataRobot CLI is installed and on your PATH. See [Getting started with the DataRobot CLI](https://docs.datarobot.com/en/docs/agentic-ai/cli/getting-started.html) for installation, then run `dr start` to select a framework. For CLI-specific issues, see [CLI troubleshooting](https://docs.datarobot.com/en/docs/agentic-ai/cli/troubleshooting.html).

### Local testing fails

Issue: Local testing encounters errors when trying to run your agent during development.

Solution: Use the CLI command to test your agent locally. This allows you to run and debug your agent code without deploying it to DataRobot. The `execute` command requires a development server to be running. You can either start it manually with `task agent:dev` (it runs continuously, so use a separate terminal), or use `START_DEV=1` to automatically start and stop it:

- Test with a basic text query: task agent:cli START_DEV=1 -- execute --user_prompt "Hello" (or start task agent:dev first, then run task agent:cli -- execute --user_prompt "Hello" )
- Test with JSON input: task agent:cli START_DEV=1 -- execute --user_prompt '{"topic": "Artificial Intelligence"}'
- Test with a completion JSON file: task agent:cli START_DEV=1 -- execute --completion_json example-completion.json
- Enable verbose logging: Add "verbose": true to the extra_body field in your completion JSON

Common issues include missing environment variables ( `DATAROBOT_API_TOKEN`, `DATAROBOT_ENDPOINT`), import issues in `myagent.py` (see [Import issues](https://docs.datarobot.com/en/docs/agentic-ai/agentic-develop/agentic-troubleshooting.html#import-issues-in-myagent-py)), and missing dependencies in `pyproject.toml`.

## Infrastructure issues

Problems with containerization, build processes, and infrastructure state management.

### Docker build fails

Issue: Docker container build encounters errors.

Solution: Test locally and check `pyproject.toml` dependencies.

### Pulumi state issues

Issue: Pulumi state is out of sync.

Solution: Run `task infra:refresh` to sync state.

### Import issues in myagent.py

Issue: Imports in `myagent.py` to files in the same folder cause silent failures in DRUM.

Solution: Use relative imports instead of package imports.

## LLM gateway issues

Issues specific to LLM gateway connectivity, model access, and configuration.

### Model access error

Issue: LLM gateway cannot connect to the model or fails with "no model access" error.

Solution: Ensure you have access to the model. If you specified a model you don't have access to (or a retired model), you can connect to the gateway, but then the action fails with a "no model access" error.

### LLM gateway configuration

Issue: LLM gateway is not properly configured.

Solution: Ensure that your organization has access to the [LLM gateway](https://docs.datarobot.com/en/docs/reference/gen-ai-ref/llm-availability.html) and that the `ENABLE_LLM_GATEWAY_INFERENCE` runtime parameter is provided in the `model-metadata.yaml` file and set to `true`.

### Non-gateway model deployment

Issue: Non-gateway model deployment fails.

Solution: If you are using a non-gateway model, run `task deploy` once even if it fails to get your LLM deployment to run.

## Accessing request headers

When your agent is deployed, you may need to access HTTP request headers for authentication, tracking, or custom metadata. DataRobot makes headers available to your agent code through the `chat()` function's `**kwargs` parameter.

### Extracting X-Untrusted-* headers

Headers with the `X-Untrusted-*` prefix are passed through from the original request and are available in the `kwargs` dictionary:

```
import asyncio
from concurrent.futures import ThreadPoolExecutor
from typing import Any, Iterator, Union
from openai.types.chat import CompletionCreateParams
from openai.types.chat.completion_create_params import (
    CompletionCreateParamsNonStreaming,
    CompletionCreateParamsStreaming,
)

def chat(
    completion_create_params: CompletionCreateParams
    | CompletionCreateParamsNonStreaming
    | CompletionCreateParamsStreaming,
    load_model_result: tuple[ThreadPoolExecutor, asyncio.AbstractEventLoop],
    **kwargs: Any,
) -> Union[CustomModelChatResponse, Iterator[CustomModelStreamingResponse]]:
    # Extract all headers from kwargs
    headers = kwargs.get("headers", {})

    # Access specific X-Untrusted-* headers
    authorization_header = headers.get("X-Untrusted-Authorization")
    custom_header = headers.get("X-Untrusted-Custom-Metadata")

    # Use headers in your agent logic
    if authorization_header:
        # Pass to downstream services, tools, etc.
        print(f"Authorization header: {authorization_header}")
```

### Common use cases

Passing authentication to external services:

```
headers = kwargs.get("headers", {})
auth_token = headers.get("X-Untrusted-Authorization")

# Use the token to authenticate with external APIs
tool_client = MyTool(auth_token=auth_token)
```

Tracking request metadata:

```
headers = kwargs.get("headers", {})
request_id = headers.get("X-Untrusted-Request-ID")
user_id = headers.get("X-Untrusted-User-ID")

# Log metadata for debugging or analytics
logging.info(f"Processing request {request_id} for user {user_id}")
```

Conditional agent behavior:

```
headers = kwargs.get("headers", {})
region = headers.get("X-Untrusted-Region")

# Adjust agent behavior based on request context
if region == "EU":
    agent = MyAgent(enable_gdpr_mode=True)
```

### Important considerations

- Only headers with the X-Untrusted-* prefix are passed through to your agent code.
- Headers are case-sensitive when accessing them from the dictionary.
- Always provide default values or check for None when accessing headers that may not be present.
- Headers are available in both streaming and non-streaming chat responses.

## Debugging tips

Useful techniques and commands for troubleshooting and debugging agent issues.

### Enable verbose logging

```
agent = MyAgent(verbose=True)
```

### Test authentication

```
from datarobot_genai.core.cli import AgentEnvironment

env = AgentEnvironment()
```

### Check environment variables

```
echo $DATAROBOT_API_TOKEN
echo $DATAROBOT_ENDPOINT
```

### Log request headers for debugging

```
import asyncio
import logging
from concurrent.futures import ThreadPoolExecutor
from typing import Any

def chat(completion_create_params, load_model_result: tuple[ThreadPoolExecutor, asyncio.AbstractEventLoop], **kwargs: Any):
    headers = kwargs.get("headers", {})

    # Log all headers to inspect what's available
    if headers:
        logging.warning(f"All headers: {dict(headers)}")

    # Continue with agent logic...
```

## Getting help

For additional assistance:

- Check the documentation for your chosen agentic framework.
- Contact DataRobot for support.
- Open an issue on the GitHub repository .
- Framework Documentation: