From 482d7970f90ce5784b9a238edbdbea73dde36cbe Mon Sep 17 00:00:00 2001
From: Lee Jackson <130007945+Imagineer99@users.noreply.github.com>
Date: Wed, 1 Jul 2026 13:47:33 +0100
Subject: [PATCH] Fix Windows Studio UTF-8 startup handling (#6614)

Extracted and narrowed from unslothai/unsloth#6543 by @TheJagStudio.

This keeps the startup/banner and text file encoding hardening separate from the already-merged Python code-exec UTF-8 fix in #6548.

Co-authored-by: Jagrat Patel <81472856+TheJagStudio@users.noreply.github.com>
---
 studio/backend/core/training/trainer.py       |  4 +-
 studio/backend/main.py                        | 12 ++++++
 studio/backend/startup_banner.py              | 20 +++++++--
 .../tests/test_startup_banner_loopback.py     | 41 +++++++++++++++++++
 unsloth_cli/commands/chat.py                  |  2 +-
 unsloth_cli/commands/studio.py                |  2 +-
 6 files changed, 73 insertions(+), 8 deletions(-)

diff --git a/studio/backend/core/training/trainer.py b/studio/backend/core/training/trainer.py
index 6f55daee39..20b2305a5a 100644
--- a/studio/backend/core/training/trainer.py
+++ b/studio/backend/core/training/trainer.py
@@ -3672,7 +3672,7 @@ class UnslothTrainer:
             return
 
         try:
-            with open(config_path, "r") as f:
+            with open(config_path, "r", encoding = "utf-8") as f:
                 config = json.load(f)
 
             # Determine training method
@@ -3686,7 +3686,7 @@ class UnslothTrainer:
             config["unsloth_training_method"] = method
             logger.info(f"Patching adapter_config.json with unsloth_training_method='{method}'")
 
-            with open(config_path, "w") as f:
+            with open(config_path, "w", encoding = "utf-8") as f:
                 json.dump(config, f, indent = 2)
 
         except Exception as e:
diff --git a/studio/backend/main.py b/studio/backend/main.py
index 0a5b775775..8b8a5fe787 100644
--- a/studio/backend/main.py
+++ b/studio/backend/main.py
@@ -24,6 +24,18 @@ os.environ["PYTHONWARNINGS"] = "ignore"
 # process is covered before its heavy ML imports.
 os.environ.setdefault("CUDA_DEVICE_ORDER", "PCI_BUS_ID")
 
+# Windows terminals default to the active system code page. Reconfigure
+# stdout/stderr before the startup banner so non-ASCII output cannot crash the
+# backend process.
+if sys.platform == "win32":
+    for _win_stream in (sys.stdout, sys.stderr):
+        if _win_stream is not None and hasattr(_win_stream, "reconfigure"):
+            try:
+                _win_stream.reconfigure(encoding = "utf-8", errors = "replace")
+            except Exception:
+                pass
+    del _win_stream
+
 # ── Windows AMD ROCm DLL injection ──────────────────────────────────────────
 # Python 3.8+ ignores PATH for extension modules; register ROCm bin dirs with
 # os.add_dll_directory() so amdhip64.dll etc. are found before any torch import.
diff --git a/studio/backend/startup_banner.py b/studio/backend/startup_banner.py
index 13d6f8ef5e..ea951a4325 100644
--- a/studio/backend/startup_banner.py
+++ b/studio/backend/startup_banner.py
@@ -12,6 +12,18 @@ import os
 import sys
 
 
+def _safe_print(text: str) -> None:
+    """Print text without crashing on terminals that cannot encode Unicode."""
+    try:
+        print(text)
+    except UnicodeEncodeError:
+        encoding = getattr(sys.stdout, "encoding", None) or "ascii"
+        try:
+            print(text.encode(encoding, errors = "replace").decode(encoding))
+        except LookupError:
+            print(text.encode("ascii", errors = "replace").decode("ascii"))
+
+
 def stdout_supports_color() -> bool:
     """True if we should emit ANSI colors."""
     if os.environ.get("NO_COLOR", "").strip():
@@ -28,9 +40,9 @@ def print_port_in_use_notice(original_port: int, new_port: int) -> None:
     """Message when the requested port is taken and another is chosen."""
     msg = f"Port {original_port} is in use, using port {new_port} instead."
     if stdout_supports_color():
-        print(f"\033[38;5;245m{msg}\033[0m")
+        _safe_print(f"\033[38;5;245m{msg}\033[0m")
     else:
-        print(msg)
+        _safe_print(msg)
 
 
 def print_studio_stop_hint() -> None:
@@ -44,7 +56,7 @@ def print_studio_stop_hint() -> None:
     def style(text: str, code: str) -> str:
         return f"{code}{text}{reset}" if use_color else text
 
-    print(
+    _safe_print(
         "\n".join(
             [
                 "",
@@ -180,4 +192,4 @@ def print_studio_access_banner(
             ]
         )
 
-    print("\n".join(lines))
+    _safe_print("\n".join(lines))
diff --git a/studio/backend/tests/test_startup_banner_loopback.py b/studio/backend/tests/test_startup_banner_loopback.py
index e82b741a7b..c8875bf5db 100644
--- a/studio/backend/tests/test_startup_banner_loopback.py
+++ b/studio/backend/tests/test_startup_banner_loopback.py
@@ -5,6 +5,9 @@
 only for the exact loopback aliases, so any other bind (e.g. a specific LAN IP)
 must show its real address."""
 
+import io
+import sys
+
 import pytest
 
 from startup_banner import print_studio_access_banner
@@ -22,3 +25,41 @@ def test_non_alias_loopback_shows_real_address(capsys):
 def test_alias_loopback_shows_canned_url(capsys, host):
     print_studio_access_banner(port = 8891, bind_host = host, display_host = host)
     assert "http://127.0.0.1:8891" in capsys.readouterr().out
+
+
+def test_banner_prints_on_strict_cp1252_stdout(monkeypatch):
+    buf = io.BytesIO()
+    stdout = io.TextIOWrapper(buf, encoding = "cp1252", errors = "strict")
+    monkeypatch.setattr(sys, "stdout", stdout)
+
+    print_studio_access_banner(port = 8891, bind_host = "127.0.0.1", display_host = "127.0.0.1")
+    stdout.flush()
+
+    out = buf.getvalue().decode("cp1252")
+    assert "? Unsloth Studio is running" in out
+
+
+def test_banner_print_fallback_handles_unknown_stdout_encoding(monkeypatch):
+    class InvalidEncodingStdout:
+        encoding = "not-a-real-codec"
+
+        def __init__(self):
+            self.buf = io.BytesIO()
+            self.inner = io.TextIOWrapper(self.buf, encoding = "cp1252", errors = "strict")
+
+        def write(self, text):
+            return self.inner.write(text)
+
+        def flush(self):
+            return self.inner.flush()
+
+        def getvalue(self):
+            self.flush()
+            return self.buf.getvalue().decode("cp1252")
+
+    stdout = InvalidEncodingStdout()
+    monkeypatch.setattr(sys, "stdout", stdout)
+
+    print_studio_access_banner(port = 8891, bind_host = "127.0.0.1", display_host = "127.0.0.1")
+
+    assert "? Unsloth Studio is running" in stdout.getvalue()
diff --git a/unsloth_cli/commands/chat.py b/unsloth_cli/commands/chat.py
index a483aeeb6c..d3bfbbf96b 100644
--- a/unsloth_cli/commands/chat.py
+++ b/unsloth_cli/commands/chat.py
@@ -71,7 +71,7 @@ def _get_base_load_in_4bit(model_config) -> bool:
         if not adapter_cfg_path.exists():
             return True
 
-        with open(adapter_cfg_path) as f:
+        with open(adapter_cfg_path, encoding = "utf-8") as f:
             adapter_cfg = json.load(f)
 
         training_method = adapter_cfg.get("unsloth_training_method")
diff --git a/unsloth_cli/commands/studio.py b/unsloth_cli/commands/studio.py
index 7a5080bd10..80641a17c3 100644
--- a/unsloth_cli/commands/studio.py
+++ b/unsloth_cli/commands/studio.py
@@ -461,7 +461,7 @@ def _write_auth_secret(path: Path, secret: str) -> None:
             os.chmod(tmp_path, 0o600)
         except OSError:
             pass
-        with os.fdopen(fd, "w") as f:
+        with os.fdopen(fd, "w", encoding = "utf-8") as f:
             fd = -1
             f.write(secret)
         os.replace(tmp_path, path)