{"record":{"id":"b44cab5cb550a72b","repo":"OpenBB-finance/OpenBB","slug":"home-or-userprofile-environment-variable-not-set","errorCode":null,"errorMessage":"HOME or USERPROFILE environment variable not set.","messagePattern":"HOME or USERPROFILE environment variable not set\\.","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"openbb_platform/extensions/platform_api/openbb_platform_api/main.py","lineNumber":43,"sourceCode":"from .utils.merge_agents import get_additional_agents, has_additional_agents\nfrom .utils.merge_apps import get_additional_apps, has_additional_apps\n\nlogger = logging.getLogger(\"openbb_platform_api\")\nlogger.setLevel(logging.INFO)\nhandler = logging.StreamHandler()\nhandler.setLevel(logging.INFO)\nformatter = logging.Formatter(\"\\n%(message)s\\n\")\nhandler.setFormatter(formatter)\nlogger.addHandler(handler)\nlogger.setLevel(logging.INFO)\n\n\n# Adds the OpenBB Environment variables to the script process.\nEnv()\nHOME = os.environ.get(\"HOME\") or os.environ.get(\"USERPROFILE\")\n\nif not HOME:\n    raise ValueError(\"HOME or USERPROFILE environment variable not set.\")\n\nCURRENT_USER_SETTINGS = os.path.join(HOME, \".openbb_platform\", \"user_settings.json\")\n# Widget filtering is optional and can be used to exclude widgets from the widgets.json file\n# Alternatively, you can supply a JSON-encoded list of API paths to ignore.\nWIDGET_SETTINGS = os.path.join(HOME, \".openbb_platform\", \"widget_settings.json\")\nkwargs = parse_args()\n_app = kwargs.pop(\"app\", None)\n\nif _app:\n    app = _app\n\nWIDGETS_PATH = kwargs.pop(\"widgets-json\", None)\nAPPS_PATH = kwargs.pop(\"apps-json\", None)\nEDITABLE = kwargs.pop(\"editable\", None) is True or WIDGETS_PATH is not None\nDEFAULT_APPS_PATH = (\n    Path(__file__).absolute().parent.joinpath(\"assets\").joinpath(\"default_apps.json\")\n)\nAGENTS_PATH = kwargs.pop(\"agents-json\", None)","sourceCodeStart":25,"sourceCodeEnd":61,"githubUrl":"https://github.com/OpenBB-finance/OpenBB/blob/3e071fcc2cd9f891cac6040ae60296dba76dab46/openbb_platform/extensions/platform_api/openbb_platform_api/main.py#L25-L61","documentation":"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.","triggerScenarios":"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.","commonSituations":"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={}).","solutions":["Set HOME in the environment: docker run -e HOME=/root ... or ENV HOME=/root in the Dockerfile","For systemd services add Environment=HOME=/var/lib/myapp (and create that directory)","If launching via subprocess, pass env={**os.environ, \"HOME\": os.path.expanduser(\"~\")} instead of env={}"],"exampleFix":"# before\nsubprocess.run([sys.executable, \"-m\", \"openbb_platform_api\"], env={})\n\n# after\nsubprocess.run([sys.executable, \"-m\", \"openbb_platform_api\"], env={**os.environ, \"HOME\": \"/home/user\"})","handlingStrategy":"validation","validationCode":"import os\n\nif not (os.environ.get(\"HOME\") or os.environ.get(\"USERPROFILE\")):\n    os.environ[\"HOME\"] = os.path.expanduser(\"~\") or \"/tmp\"\n    # only then import\nimport openbb_platform_api.main  # noqa: E402","typeGuard":"def home_env_available() -> bool:\n    import os\n    return bool(os.environ.get(\"HOME\") or os.environ.get(\"USERPROFILE\"))","tryCatchPattern":"try:\n    import openbb_platform_api.main as main\nexcept ValueError as e:\n    if \"HOME or USERPROFILE\" in str(e):\n        import os\n        os.environ.setdefault(\"HOME\", \"/tmp\")\n        import openbb_platform_api.main as main  # retry once\n    else:\n        raise","preventionTips":["Set ENV HOME in Dockerfiles that run the platform API","For systemd services add Environment=HOME=... and create the directory","Never pass env={} to subprocess without re-injecting HOME"],"tags":["environment","home-directory","docker","deployment"],"backgroundTag":null,"analyzedSha":"3e071fcc2cd9f891cac6040ae60296dba76dab46","analyzedAt":"2026-08-14T23:40:48.960Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}