fix: handle missing clipboard in headless environments for langflow api-key command

pyperclip.copy() was called without error handling, causing an unhandled
PyperclipException in Docker/SSH environments where no clipboard mechanism
is available. The crash happened after the key was generated and the previous
one deleted, making the new key unrecoverable.

- Wrap pyperclip.copy() in try/except; show key regardless of clipboard availability
- Adapt banner hint text based on whether clipboard copy succeeded
- Add unit tests covering headless fallback and UnicodeEncodeError scenarios

Author: andifilhohub

src/backend/base/langflow/__main__.py

@@ -950,13 +950,24 @@ def api_key_banner(unmasked_api_key) -> None:
     is_mac = platform.system() == "Darwin"
     import pyperclip
 
-    pyperclip.copy(unmasked_api_key.api_key)
+    clipboard_available = False
+    try:
+        pyperclip.copy(unmasked_api_key.api_key)
+        clipboard_available = True
+    except Exception:  # noqa: BLE001
+        pass
+
+    clipboard_hint = (
+        f"The API key has been copied to your clipboard. [bold]{['Ctrl', 'Cmd'][is_mac]} + V[/bold] to paste it."
+        if clipboard_available
+        else "Store this key securely — it will not be displayed again."
+    )
     panel = Panel(
         f"[bold]API Key Created Successfully:[/bold]\n\n"
         f"[bold blue]{unmasked_api_key.api_key}[/bold blue]\n\n"
         "This is the only time the API key will be displayed. \n"
         "Make sure to store it in a secure location. \n\n"
-        f"The API key has been copied to your clipboard. [bold]{['Ctrl', 'Cmd'][is_mac]} + V[/bold] to paste it.",
+        f"{clipboard_hint}",
         box=box.ROUNDED,
         border_style="blue",
         expand=False,
@@ -972,8 +983,9 @@ def api_key_banner(unmasked_api_key) -> None:
         logger.info(unmasked_api_key.api_key)
         logger.info("This is the only time the API key will be displayed.")
         logger.info("Make sure to store it in a secure location.")
-        ctrl_cmd = "Ctrl" if not is_mac else "Cmd"
-        logger.info(f"The API key has been copied to your clipboard. {ctrl_cmd} + V to paste it.")
+        if clipboard_available:
+            ctrl_cmd = "Ctrl" if not is_mac else "Cmd"
+            logger.info(f"The API key has been copied to your clipboard. {ctrl_cmd} + V to paste it.")
 
 
 def main() -> None:

src/backend/tests/unit/test_cli.py

@@ -1,11 +1,11 @@
 import socket
 import threading
 import time
-from unittest.mock import patch
+from unittest.mock import MagicMock, patch
 
 import pytest
 import typer
-from langflow.__main__ import _create_superuser, app, get_number_of_workers
+from langflow.__main__ import _create_superuser, api_key_banner, app, get_number_of_workers
 from lfx.services import deps
 
 
@@ -147,6 +147,101 @@ async def test_failed_auth_token_validation(self, client, active_super_user):  #
             assert exc_info.value.exit_code == 1
 
 
+class TestApiKeyBanner:
+    """Tests for api_key_banner clipboard fallback (headless environments)."""
+
+    def _make_key(self, value: str = "sk-test-1234"):
+        mock = MagicMock()
+        mock.api_key = value
+        return mock
+
+    def test_clipboard_available_copies_key(self):
+        """When pyperclip works, key is copied and clipboard hint is shown."""
+        key = self._make_key()
+        with (
+            patch("pyperclip.copy") as mock_copy,
+            patch("langflow.__main__.Console") as mock_console_cls,
+        ):
+            mock_console = MagicMock()
+            mock_console_cls.return_value = mock_console
+
+            api_key_banner(key)
+
+            mock_copy.assert_called_once_with(key.api_key)
+            printed = mock_console.print.call_args[0][0]
+            assert "clipboard" in str(printed).lower()
+            assert key.api_key in str(printed)
+
+    def test_clipboard_unavailable_still_prints_key(self):
+        """When pyperclip raises (headless/Docker), key is still displayed on stdout."""
+        key = self._make_key()
+        with (
+            patch("pyperclip.copy", side_effect=Exception("No clipboard mechanism")),
+            patch("langflow.__main__.Console") as mock_console_cls,
+        ):
+            mock_console = MagicMock()
+            mock_console_cls.return_value = mock_console
+
+            # Must NOT raise
+            api_key_banner(key)
+
+            mock_console.print.assert_called_once()
+            printed = mock_console.print.call_args[0][0]
+            assert key.api_key in str(printed)
+
+    def test_clipboard_unavailable_shows_fallback_hint(self):
+        """When clipboard is unavailable, hint text must not mention clipboard."""
+        key = self._make_key()
+        with (
+            patch("pyperclip.copy", side_effect=Exception("No clipboard mechanism")),
+            patch("langflow.__main__.Console") as mock_console_cls,
+        ):
+            mock_console = MagicMock()
+            mock_console_cls.return_value = mock_console
+
+            api_key_banner(key)
+
+            printed = str(mock_console.print.call_args[0][0])
+            assert "clipboard" not in printed.lower()
+            assert "securely" in printed.lower()
+
+    def test_unicode_error_fallback_with_clipboard(self):
+        """On UnicodeEncodeError, logger fallback includes clipboard message when available."""
+        key = self._make_key()
+        with (
+            patch("pyperclip.copy"),
+            patch("langflow.__main__.Console") as mock_console_cls,
+            patch("langflow.__main__.logger") as mock_logger,
+        ):
+            mock_console = MagicMock()
+            mock_console.print.side_effect = UnicodeEncodeError("utf-8", b"", 0, 1, "reason")
+            mock_console_cls.return_value = mock_console
+
+            api_key_banner(key)
+
+            logged_messages = " ".join(str(c) for c in mock_logger.info.call_args_list)
+            assert key.api_key in logged_messages
+            assert "clipboard" in logged_messages.lower()
+
+    def test_unicode_error_fallback_without_clipboard(self):
+        """On UnicodeEncodeError, logger fallback omits clipboard message when unavailable."""
+        key = self._make_key()
+        with (
+            patch("pyperclip.copy", side_effect=Exception("No clipboard mechanism")),
+            patch("langflow.__main__.Console") as mock_console_cls,
+            patch("langflow.__main__.logger") as mock_logger,
+        ):
+            mock_console = MagicMock()
+            mock_console.print.side_effect = UnicodeEncodeError("utf-8", b"", 0, 1, "reason")
+            mock_console_cls.return_value = mock_console
+
+            api_key_banner(key)
+
+            logged_messages = " ".join(str(c) for c in mock_logger.info.call_args_list)
+            assert key.api_key in logged_messages
+            assert "clipboard" not in logged_messages.lower()
+
+
 def test_get_number_of_workers():
     """Test that get_number_of_workers uses cpu_count on Linux."""
     with (