{"id":"9c83c8a0ebab88b5","repo":"pallets/flask","slug":"if-an-instance-path-is-provided-it-must-be-absolut","errorCode":null,"errorMessage":"If an instance path is provided it must be absolute. A relative path was given instead.","messagePattern":"If an instance path is provided it must be absolute\\. A relative path was given instead\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/flask/sansio/app.py","lineNumber":303,"sourceCode":"        host_matching: bool = False,\n        subdomain_matching: bool = False,\n        template_folder: str | os.PathLike[str] | None = \"templates\",\n        instance_path: str | None = None,\n        instance_relative_config: bool = False,\n        root_path: str | None = None,\n    ) -> None:\n        super().__init__(\n            import_name=import_name,\n            static_folder=static_folder,\n            static_url_path=static_url_path,\n            template_folder=template_folder,\n            root_path=root_path,\n        )\n\n        if instance_path is None:\n            instance_path = self.auto_find_instance_path()\n        elif not os.path.isabs(instance_path):\n            raise ValueError(\n                \"If an instance path is provided it must be absolute.\"\n                \" A relative path was given instead.\"\n            )\n\n        #: Holds the path to the instance folder.\n        #:\n        #: .. versionadded:: 0.8\n        self.instance_path = instance_path\n\n        #: The configuration dictionary as :class:`Config`.  This behaves\n        #: exactly like a regular dictionary but supports additional methods\n        #: to load a config from files.\n        self.config = self.make_config(instance_relative_config)\n\n        #: An instance of :attr:`aborter_class` created by\n        #: :meth:`make_aborter`. This is called by :func:`flask.abort`\n        #: to raise HTTP errors, and can be called directly as well.\n        #:","sourceCodeStart":285,"sourceCodeEnd":321,"githubUrl":"https://github.com/pallets/flask/blob/6a2f545bfd8ed31e19066a299296917e034aca58/src/flask/sansio/app.py#L285-L321","documentation":"Raised in `Flask.__init__` (src/flask/sansio/app.py:303) when the `instance_path` constructor argument is set but is not an absolute path. Flask's instance folder is used as a filesystem anchor for config files, uploads, and the SQLite-style data that lives outside the package; a relative path would resolve differently depending on the process's current working directory, so Flask refuses it outright instead of guessing.","triggerScenarios":"Calling `Flask(__name__, instance_path='instance')` or any other relative string (e.g. './data', 'config'). Only the explicit-argument branch triggers it — when `instance_path` is omitted, `auto_find_instance_path()` computes an absolute default and this check is skipped.","commonSituations":"Passing a path copied from a config file or environment variable that was written relative to the project root; constructing the app in a factory and hardcoding 'instance'; Docker/CI setups where an env var like INSTANCE_PATH is set to a relative value; Windows paths like 'C:folder' that are not absolute per os.path.isabs.","solutions":["Build the path absolutely from a known anchor, e.g. `os.path.join(os.path.dirname(os.path.abspath(__file__)), 'instance')` or `Path(__file__).parent / 'instance'`.","Wrap externally supplied values with `os.path.abspath(value)` before passing them to Flask if resolving against the current working directory is actually what you intend.","Omit `instance_path` entirely and let Flask auto-detect it next to the package or module."],"exampleFix":"# before\napp = Flask(__name__, instance_path=\"instance\")\n\n# after\nimport os\napp = Flask(\n    __name__,\n    instance_path=os.path.join(os.path.dirname(os.path.abspath(__file__)), \"instance\"),\n)","handlingStrategy":"validation","validationCode":"import os\ninstance_path = os.path.abspath(instance_path)  # ensure absolute\nassert os.path.isabs(instance_path)\napp = Flask(__name__, instance_path=instance_path)","typeGuard":"def is_valid_instance_path(p):\n    import os\n    return isinstance(p, str) and os.path.isabs(p)","tryCatchPattern":"try:\n    app = Flask(__name__, instance_path=path)\nexcept ValueError as e:\n    if 'must be absolute' in str(e):\n        app = Flask(__name__, instance_path=os.path.abspath(path))","preventionTips":["Always build instance_path with os.path.abspath() or pathlib.Path(...).resolve()","Never pass user-supplied or config-file relative paths directly; normalize at load time","Prefer Flask's default instance path unless you genuinely need a custom one"],"tags":["flask","python","configuration","filesystem","app-init"],"analyzedSha":"6a2f545bfd8ed31e19066a299296917e034aca58","analyzedAt":"2026-07-31T19:13:49.921Z","schemaVersion":2}