Common Deployment Issues and Resolutions for the AI Hedge Fund Project

The most frequent deployment failures in the virattt/ai-hedge-fund repository stem from missing environment variables, unconfigured API rate limits, and Docker service misconfigurations, all resolvable through proper .env setup, cache utilization, and GPU driver installation.

The AI Hedge Fund is a modular Python application that orchestrates multiple LLM agents to simulate trading strategies. Successfully deploying this system requires coordinating environment variables, external financial data APIs, and optional local inference via Ollama. This guide addresses the common deployment issues and resolutions encountered when running the application locally, via Docker, or in cloud environments, with specific references to the source code implementation.

Environment Variable Configuration Errors

The Problem

Running the application without a properly configured .env file causes immediate authentication failures. The system attempts to read API keys from the environment, receiving None values when variables are undefined, which results in incomplete HTTP headers being sent to external services.

Root Cause in Source Code

In src/tools/api.py, the function _make_api_request retrieves FINANCIAL_DATASETS_API_KEY using os.environ.get("FINANCIAL_DATASETS_API_KEY") at lines 70-74. Similarly, src/llm/models.py handles provider-specific keys like OPENAI_API_KEY and ANTHROPIC_API_KEY using the same pattern at lines 140-168. When these environment variables are absent, request headers remain incomplete, triggering 401 or 403 errors from remote APIs.

Resolution Steps

1. Initialize the environment file – The docker/run.sh wrapper automatically copies .env.example to .env if the latter is missing at lines 44-48.

2. Configure API credentials – Edit .env to replace placeholder values with actual keys from Financial Datasets, OpenAI, Anthropic, or other providers as specified in .env.example at lines 1-38.

3. Verify visibility – Run poetry run python -c "import os; print(os.getenv('OPENAI_API_KEY'))" to confirm variables are accessible inside the container, which mounts the file via -v $(pwd)/.env:/app/.env at lines 65-66 in run.sh.

Financial Datasets API Rate Limiting and 429 Errors

The Problem

When the Financial Datasets API returns HTTP 429 (Too Many Requests), the application may abort or return empty datasets, causing downstream agents to generate no trading signals.

Backoff Implementation

The _make_api_request function in src/tools/api.py implements a linear backoff strategy at lines 43-55, waiting 60 seconds initially and adding 30 seconds per subsequent retry. However, if the caller such as get_prices does not handle the final 429 after exhausting max_retries=3, an empty list propagates to the analysis agents.

Mitigation Strategies

• Allow sufficient retries – Ensure the default max_retries=3 parameter in _make_api_request meets your usage patterns.
• Increase API quotas – Contact the Financial Datasets provider to raise rate limits or distribute requests over time.
• Enable caching – The src/data/cache.py layer stores successful API responses, significantly reducing repeated calls during backtesting at lines 60-73.

Docker Image Build and Dependency Failures

The Problem

Executing docker build may fail with missing dependencies, network timeouts, or permission errors, preventing container creation.

Build Process Overview

The docker/Dockerfile installs Poetry version 1.7.1 at lines 8-10, then copies pyproject.toml and poetry.lock before running poetry install at lines 11-16. This approach ensures reproducible builds but requires network access to PyPI and compatibility between the pinned Poetry version and the lockfile.

Fixing Build Issues

1. Check network connectivity – The build process must download packages from PyPI; corporate firewalls or offline environments will cause failures.

2. Pin Poetry versions – The Dockerfile already pins Poetry to 1.7.1. If upgrading Poetry, update both the Dockerfile and regenerate poetry.lock using the new version.

3. Debug verbose builds – Run docker build --no-cache -t ai-hedge-fund -f docker/Dockerfile .. to identify the exact layer where installation fails.

Ollama LLM Service Startup and Connectivity Issues

The Problem

Using the --ollama flag results in "Ollama is not running" errors or model pull failures, preventing local LLM inference.

Embedded vs External Ollama

The docker/run.sh script supports two modes: launching an embedded Ollama container via Docker Compose with the embedded-ollama profile at lines 69-73 and 122-124, or connecting to an external instance via --ollama-base-url. The script polls http://localhost:11434/api/version at lines 76-82 to verify readiness before proceeding.

Service Detection Logic

In src/utils/docker.py, utility functions check Ollama availability and manage model operations. The script waits for the service to respond with a valid JSON version object before executing ollama pull commands.

Troubleshooting Steps

1. Install Docker Compose – Ensure the docker-compose binary or docker compose plugin is available; the script checks for this at lines 36-40 and aborts if missing.

2. Start Ollama manually – If the script fails, launch the service directly: docker compose up -d ollama.

3. Verify connectivity – Test the endpoint: curl http://localhost:11434/api/version. Expect a JSON response containing version information.

4. Pull models explicitly – Use ./run.sh pull llama3 to download models; the script waits for Ollama startup and executes ollama pull inside the container at lines 96-104 and 124-126.

GPU Configuration Not Detected in Containers

The Problem

GPU-accelerated inference fails to activate, causing slower CPU-only LLM processing despite available NVIDIA hardware.

NVIDIA GPU Configuration

The docker/run.sh script detects NVIDIA GPUs by executing nvidia-smi at lines 58-61. When detected, it appends an additional compose file (e.g., docker-compose.nvidia.yml) to enable GPU passthrough. However, this requires the NVIDIA Container Toolkit installed on the host.

Verification Commands

1. Install prerequisites – Follow the official NVIDIA Container Toolkit installation guide to enable GPU support in Docker containers.

2. Verify GPU access – Run docker run --gpus all nvidia/cuda:12.0-base nvidia-smi to confirm the GPU is visible inside containers.

3. Enable automatic detection – Execute ./run.sh --ollama without additional flags; the script automatically adds the GPU profile when nvidia-smi is present on the host system.

Command-Line Argument Parsing and Validation Errors

The Problem

Passing invalid date formats or omitting required parameters causes immediate script termination or empty portfolio results.

Input Requirements

The src/cli/input.py module parses command-line arguments, expecting ISO-format dates (YYYY-MM-DD) for --start-date and --end-date parameters. The system does not validate ticker symbols against the data provider; supplying invalid symbols results in empty data sets that propagate through the agent workflow without generating trading signals.

Common Mistakes

• Date format errors – Using 01/01/2024 instead of 2024-01-01 causes parsing failures.
• Missing tickers – Omitting --ticker produces an empty watchlist, preventing agent execution.
• Invalid symbols – Non-existent ticker codes return empty price data from the Financial Datasets API.

Resolution

• Consult the help menu – Run ./run.sh --help to view available options and formatting requirements at lines 3-28 in run.sh.
• Validate date formats – Use ISO 8601 format: --start-date 2024-01-01 --end-date 2024-03-31.
• Verify ticker existence – Confirm symbols like AAPL, MSFT, or NVDA are available on the Financial Datasets platform before execution.

Missing Python Dependencies at Runtime

The Problem

Executing the CLI directly via poetry run python src/main.py raises ModuleNotFoundError for packages like pandas, langgraph, or openai.

Poetry Environment Issues

The repository uses Poetry for dependency management defined in pyproject.toml. The docker/Dockerfile executes poetry install during image build at lines 11-16, but local development environments often skip this step or use incompatible Python versions.

Resolution Steps

1. Install dependencies – Execute poetry install from the project root to create the virtual environment and install all packages from the lockfile.

2. Activate the environment – Use poetry shell to enter the virtual environment, or prefix commands with poetry run to ensure correct package resolution.

3. Verify installation – Run poetry run python -c "import langgraph; import pandas; print('Dependencies OK')" to confirm critical dependencies are available.

Summary

• Environment configuration is the most frequent source of deployment failures; always verify .env contains valid FINANCIAL_DATASETS_API_KEY and LLM provider keys before starting containers.
• API rate limiting requires utilizing the built-in retry logic with caching enabled to handle HTTP 429 errors gracefully.
• Docker builds need reliable network access to PyPI and compatible Poetry versions to resolve dependencies correctly.
• Ollama services depend on Docker Compose availability and proper health checking at localhost:11434 before model execution.
• GPU acceleration demands the NVIDIA Container Toolkit and successful detection via nvidia-smi to enable hardware-accelerated inference.
• CLI validation depends on ISO date formats (YYYY-MM-DD) and valid ticker symbols to prevent empty agent workflows.
• Python dependencies require running poetry install before local execution to prevent ModuleNotFoundError exceptions.

Frequently Asked Questions

Why does the application fail immediately with authentication errors?

Authentication failures occur when the .env file is missing or contains placeholder API keys. The src/tools/api.py file attempts to read FINANCIAL_DATASETS_API_KEY via os.environ.get(), and src/llm/models.py retrieves provider-specific keys like OPENAI_API_KEY. If these return None, the application sends requests without proper headers, resulting in 401 or 403 errors. Resolve this by copying .env.example to .env and populating it with valid credentials.

How do I resolve HTTP 429 errors from the Financial Datasets API?

HTTP 429 errors indicate rate limiting. The _make_api_request function in src/tools/api.py implements a linear backoff strategy, waiting 60 seconds initially and adding 30 seconds per retry. To resolve persistent 429 errors, ensure max_retries is set sufficiently high in your configuration, enable the caching layer in src/data/cache.py to reduce redundant calls, or contact your API provider to increase quota limits.

Why is Ollama not starting when I use the --ollama flag?

The docker/run.sh script attempts to launch Ollama via Docker Compose using the embedded-ollama profile, then polls http://localhost:11434/api/version to verify readiness. Failures typically occur when Docker Compose is not installed (the script checks for this at lines 36-40), when the Ollama container fails to start due to port conflicts, or when the health check times out. Resolve this by ensuring Docker Compose is available, starting the service manually with docker compose up -d ollama, and verifying connectivity with curl http://localhost:11434/api/version.

How do I enable GPU acceleration for Ollama inference?

GPU acceleration requires the NVIDIA Container Toolkit installed on the host system. The docker/run.sh script detects NVIDIA hardware by executing nvidia-smi at lines 58-61 and automatically appends the GPU-specific compose file when detected. If GPU acceleration fails, verify your installation by running docker run --gpus all nvidia/cuda:12.0-base nvidia-smi. If this command fails, install the NVIDIA Container Toolkit following the official NVIDIA documentation, then restart Docker and rerun the hedge fund script with the --ollama flag.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}