From 47bbb8ab445534de0734525957aea79bdb0905b4 Mon Sep 17 00:00:00 2001
From: Joao Moura <joaomdmoura@gmail.com>
Date: Mon, 13 Jul 2026 21:48:34 -0700
Subject: [PATCH] Make missing OPENAI_API_KEY error actionable

The OpenAI provider raised a bare "OPENAI_API_KEY is required", which
misdirects CrewAI AMP users who configured an org-wide LLM Connection.
The error now explains the remediation (set the OPENAI_API_KEY
environment variable or pass api_key to LLM()) and clarifies that
org-wide LLM Connections do not apply to code-first AMP deployments,
which read keys from deployment environment variables.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 lib/cli/tests/deploy/test_validate.py         |  6 +++++-
 .../llms/providers/openai/completion.py       |  8 +++++++-
 lib/crewai/tests/llms/openai/test_openai.py   | 19 +++++++++++++++++++
 3 files changed, 31 insertions(+), 2 deletions(-)

diff --git a/lib/cli/tests/deploy/test_validate.py b/lib/cli/tests/deploy/test_validate.py
index 31ecb0c8b..21e8d8826 100644
--- a/lib/cli/tests/deploy/test_validate.py
+++ b/lib/cli/tests/deploy/test_validate.py
@@ -383,7 +383,11 @@ def test_classify_missing_openai_key_is_warning(tmp_path: Path) -> None:
     v._classify_import_error(
         "ImportError",
         "Error importing native provider: 1 validation error for OpenAICompletion\n"
-        "  Value error, OPENAI_API_KEY is required",
+        "  Value error, OPENAI_API_KEY is required. Set the OPENAI_API_KEY "
+        "environment variable or pass api_key to LLM(). On CrewAI AMP, "
+        "code-first deployments read API keys from deployment environment "
+        "variables — org-wide LLM Connections do not apply to code-first "
+        "deployments.",
         tb="",
     )
     assert len(v.results) == 1
diff --git a/lib/crewai/src/crewai/llms/providers/openai/completion.py b/lib/crewai/src/crewai/llms/providers/openai/completion.py
index 78e8d23e8..1810eecf5 100644
--- a/lib/crewai/src/crewai/llms/providers/openai/completion.py
+++ b/lib/crewai/src/crewai/llms/providers/openai/completion.py
@@ -387,7 +387,13 @@ class OpenAICompletion(BaseLLM):
         if self.api_key is None:
             self.api_key = os.getenv("OPENAI_API_KEY")
             if self.api_key is None:
-                raise ValueError("OPENAI_API_KEY is required")
+                raise ValueError(
+                    "OPENAI_API_KEY is required. Set the OPENAI_API_KEY "
+                    "environment variable or pass api_key to LLM(). On CrewAI "
+                    "AMP, code-first deployments read API keys from deployment "
+                    "environment variables — org-wide LLM Connections do not "
+                    "apply to code-first deployments."
+                )
 
         base_params = {
             "api_key": self.api_key,
diff --git a/lib/crewai/tests/llms/openai/test_openai.py b/lib/crewai/tests/llms/openai/test_openai.py
index d5bc797d8..58053ca9a 100644
--- a/lib/crewai/tests/llms/openai/test_openai.py
+++ b/lib/crewai/tests/llms/openai/test_openai.py
@@ -618,6 +618,25 @@ def test_openai_get_client_params_no_base_url(monkeypatch):
     assert "base_url" not in client_params or client_params.get("base_url") is None
 
 
+def test_openai_missing_api_key_error_is_actionable(monkeypatch):
+    """
+    Test that the missing-API-key error explains how to fix it: set the
+    OPENAI_API_KEY environment variable or pass api_key, and clarifies that
+    org-wide LLM Connections do not apply to code-first CrewAI AMP deployments.
+    """
+    monkeypatch.delenv("OPENAI_API_KEY", raising=False)
+
+    llm = OpenAICompletion(model="gpt-4o")
+    with pytest.raises(ValueError) as exc_info:
+        llm._get_client_params()
+
+    message = str(exc_info.value)
+    assert "OPENAI_API_KEY environment variable" in message
+    assert "api_key" in message
+    assert "org-wide LLM Connections do not apply to code-first deployments" in message
+    assert "deployment environment variables" in message
+
+
 def test_openai_streaming_with_response_model():
     """
     Test that streaming with response_model works correctly and doesn't call invalid API methods.