Skip to content
For Self-Managed AI Platform users running v11.1, see the on-premise platform documentation
Agentic AI > Develop agentic workflows > Troubleshooting

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.

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: Run task start to select framework.

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 agent.py (see Import issues), 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 refresh to sync state.

Import issues in agent.py

Issue: Imports in agent.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 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:

def chat(
    completion_create_params: CompletionCreateParams
    | CompletionCreateParamsNonStreaming
    | CompletionCreateParamsStreaming,
    model: str,
    **kwargs,
) -> 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 logging

def chat(completion_create_params, model, **kwargs):
    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: