OpenBB-finance/OpenBB · error · ValueError

HOME or USERPROFILE environment variable not set.

Error message

HOME or USERPROFILE environment variable not set.

What it means

ValueError raised at import time of openbb_platform_api.main when neither HOME nor USERPROFILE is set in the environment. The module needs a home directory to locate ~/.openbb_platform/user_settings.json and widget_settings.json, so it refuses to start without one.

Source

Thrown at openbb_platform/extensions/platform_api/openbb_platform_api/main.py:43

from .utils.merge_agents import get_additional_agents, has_additional_agents
from .utils.merge_apps import get_additional_apps, has_additional_apps

logger = logging.getLogger("openbb_platform_api")
logger.setLevel(logging.INFO)
handler = logging.StreamHandler()
handler.setLevel(logging.INFO)
formatter = logging.Formatter("\n%(message)s\n")
handler.setFormatter(formatter)
logger.addHandler(handler)
logger.setLevel(logging.INFO)


# Adds the OpenBB Environment variables to the script process.
Env()
HOME = os.environ.get("HOME") or os.environ.get("USERPROFILE")

if not HOME:
    raise ValueError("HOME or USERPROFILE environment variable not set.")

CURRENT_USER_SETTINGS = os.path.join(HOME, ".openbb_platform", "user_settings.json")
# Widget filtering is optional and can be used to exclude widgets from the widgets.json file
# Alternatively, you can supply a JSON-encoded list of API paths to ignore.
WIDGET_SETTINGS = os.path.join(HOME, ".openbb_platform", "widget_settings.json")
kwargs = parse_args()
_app = kwargs.pop("app", None)

if _app:
    app = _app

WIDGETS_PATH = kwargs.pop("widgets-json", None)
APPS_PATH = kwargs.pop("apps-json", None)
EDITABLE = kwargs.pop("editable", None) is True or WIDGETS_PATH is not None
DEFAULT_APPS_PATH = (
    Path(__file__).absolute().parent.joinpath("assets").joinpath("default_apps.json")
)
AGENTS_PATH = kwargs.pop("agents-json", None)

View on GitHub (pinned to 3e071fcc2c)

Solutions

1. Set HOME in the environment: docker run -e HOME=/root ... or ENV HOME=/root in the Dockerfile
2. For systemd services add Environment=HOME=/var/lib/myapp (and create that directory)
3. If launching via subprocess, pass env={**os.environ, "HOME": os.path.expanduser("~")} instead of env={}

Example fix

# before
subprocess.run([sys.executable, "-m", "openbb_platform_api"], env={})

# after
subprocess.run([sys.executable, "-m", "openbb_platform_api"], env={**os.environ, "HOME": "/home/user"})

import os

if not (os.environ.get("HOME") or os.environ.get("USERPROFILE")):
    os.environ["HOME"] = os.path.expanduser("~") or "/tmp"
    # only then import
import openbb_platform_api.main  # noqa: E402

def home_env_available() -> bool:
    import os
    return bool(os.environ.get("HOME") or os.environ.get("USERPROFILE"))

try:
    import openbb_platform_api.main as main
except ValueError as e:
    if "HOME or USERPROFILE" in str(e):
        import os
        os.environ.setdefault("HOME", "/tmp")
        import openbb_platform_api.main as main  # retry once
    else:
        raise

When it happens

Trigger: Running under a minimal Docker image, a cron job, a systemd service, or a CI runner where the user has no home directory env (common with UserDirective=nobody or unset *clear_environment* settings). Importing openbb_platform_api.main in such an environment fails immediately.

Common situations: Docker containers with an empty env, scratch/distroless images, CI containers running as uid without HOME, Kubernetes pods with env.value clearing, subprocess calls passing a scrubbed env (env={}).

Related errors

• Failed to cast {value} to bool.

AI-assisted analysis of OpenBB-finance/OpenBB@3e071fcc2c (2026-08-14). Data as JSON: /api/errors/b44cab5cb550a72b. Report an issue: GitHub.