From 0199b519e1f98bd9a108b91fc5ea3a489a728d9f Mon Sep 17 00:00:00 2001
From: "Parker J. Rule" <pjrule@users.noreply.github.com>
Date: Tue, 8 Sep 2026 13:03:14 -0400
Subject: [PATCH] fix(cli): clarify missing deploy config (#8854)

Shows an actionable, docs-linked error when `langgraph deploy` is run
without a `langgraph.json` instead of exposing a traceback.
---
 libs/cli/langgraph_cli/deploy.py          | 10 +++++++++
 libs/cli/tests/unit_tests/cli/test_cli.py | 25 +++++++++++++++++++++++
 2 files changed, 35 insertions(+)

diff --git a/libs/cli/langgraph_cli/deploy.py b/libs/cli/langgraph_cli/deploy.py
index 822028cb2..a6e8403e6 100644
--- a/libs/cli/langgraph_cli/deploy.py
+++ b/libs/cli/langgraph_cli/deploy.py
@@ -1603,6 +1603,16 @@ def _deploy_cmd(
 
     # -- 1. Preflight --
     validate_deploy_commands(install_command, build_command)
+    if not config.exists():
+        message = (
+            "We couldn't find a langgraph.json file. Run `langgraph deploy` from "
+            "the root of a LangSmith Deployment project. To get started, visit "
+            "https://docs.langchain.com/langsmith/deployment-quickstart."
+        )
+        if json_output:
+            em.error(message)
+            raise click.exceptions.Exit(1)
+        raise click.ClickException(message)
     config_json = langgraph_cli.config.validate_config_file(config)
     warn_non_wolfi_distro(config_json, emit=em.note)
 
diff --git a/libs/cli/tests/unit_tests/cli/test_cli.py b/libs/cli/tests/unit_tests/cli/test_cli.py
index 8b3ae47c6..ca0ec7a04 100644
--- a/libs/cli/tests/unit_tests/cli/test_cli.py
+++ b/libs/cli/tests/unit_tests/cli/test_cli.py
@@ -320,6 +320,31 @@ def test_top_level_help_truncates_command_descriptions_to_single_line() -> None:
     assert "[Beta] List LangSmith Deployments." in deploy_list_line
 
 
+def test_deploy_missing_config_shows_actionable_error(tmp_path, monkeypatch) -> None:
+    runner = CliRunner()
+    monkeypatch.chdir(tmp_path)
+
+    result = runner.invoke(cli, ["deploy"])
+
+    assert result.exit_code == 1
+    assert "We couldn't find a langgraph.json file." in result.output
+    assert "Run `langgraph deploy` from the root" in result.output
+    assert "https://docs.langchain.com/langsmith/deployment-quickstart" in result.output
+    assert "Traceback" not in result.output
+
+
+def test_deploy_missing_config_emits_json_error(tmp_path, monkeypatch) -> None:
+    runner = CliRunner()
+    monkeypatch.chdir(tmp_path)
+
+    result = runner.invoke(cli, ["deploy", "--json"])
+
+    assert result.exit_code == 1
+    events = [json.loads(line) for line in result.output.splitlines()]
+    assert events[-1]["event"] == "error"
+    assert "We couldn't find a langgraph.json file." in events[-1]["message"]
+
+
 def test_dev_command_requires_ssl_certfile_and_keyfile_together(tmp_path) -> None:
     config_path = tmp_path / "langgraph.json"
     config_path.write_text(