{"record":{"id":"58975a9704ed4b7b","repo":"django/django","slug":"unable-to-load-the-spatialite-library-extension-as","errorCode":null,"errorMessage":"Unable to load the SpatiaLite library extension as specified in your SPATIALITE_LIBRARY_PATH setting.","messagePattern":"Unable to load the SpatiaLite library extension as specified in your SPATIALITE_LIBRARY_PATH setting\\.","errorType":"exception","errorClass":"ImproperlyConfigured","httpStatus":null,"severity":"critical","filePath":"django/contrib/gis/db/backends/spatialite/base.py","lineNumber":56,"sourceCode":"        super().__init__(*args, **kwargs)\n\n    def get_new_connection(self, conn_params):\n        conn = super().get_new_connection(conn_params)\n        # Enabling extension loading on the SQLite connection.\n        try:\n            conn.enable_load_extension(True)\n        except AttributeError:\n            raise ImproperlyConfigured(\n                \"SpatiaLite requires SQLite to be configured to allow \"\n                \"extension loading.\"\n            )\n        # Load the SpatiaLite library extension on the connection.\n        for path in self.lib_spatialite_paths:\n            try:\n                conn.load_extension(path)\n            except Exception:\n                if getattr(settings, \"SPATIALITE_LIBRARY_PATH\", None):\n                    raise ImproperlyConfigured(\n                        \"Unable to load the SpatiaLite library extension \"\n                        \"as specified in your SPATIALITE_LIBRARY_PATH setting.\"\n                    )\n                continue\n            else:\n                break\n        else:\n            raise ImproperlyConfigured(\n                \"Unable to load the SpatiaLite library extension. \"\n                \"Library names tried: %s\" % \", \".join(self.lib_spatialite_paths)\n            )\n        return conn\n\n    def prepare_database(self):\n        super().prepare_database()\n        # Check if spatial metadata have been initialized in the database\n        with self.cursor() as cursor:\n            cursor.execute(\"PRAGMA table_info(geometry_columns);\")","sourceCodeStart":38,"sourceCodeEnd":74,"githubUrl":"https://github.com/django/django/blob/ae25a40be07e8a749edf526df37c93e59d4a22c9/django/contrib/gis/db/backends/spatialite/base.py#L38-L74","documentation":"Raised as ImproperlyConfigured when SPATIALITE_LIBRARY_PATH is set in settings but conn.load_extension(path) raises for that exact path. The setting is treated as authoritative, so a failure on it is fatal rather than falling through to auto-detection. It means the file is missing, not loadable, or the wrong arch.","triggerScenarios":"First connection under ENGINE=spatialite with SPATIALITE_LIBRARY_PATH defined; get_new_connection loops over lib_spatialite_paths at base.py:51, the first entry (the setting) fails load_extension, and the check at base.py:55 raises.","commonSituations":"Path points to a non-existent .so/.dylib; pointing to libspatialite.so.7 when mod_spatialite.so is required; wrong architecture (arm64 vs x86_64) after a CPU migration; SPATIALITE_LIBRARY_PATH copied from a tutorial for a different OS.","solutions":["Verify the file exists at the configured path and that `python -c \"import ctypes; ctypes.CDLL('/that/path')\"` loads it.","Point SPATIALITE_LIBRARY_PATH at mod_spatialite.so (the loadable SQLite module) rather than the plain libspatialite shared library.","Remove the setting entirely and let Django auto-detect via find_library('spatialite') / mod_spatialite.","Reinstall libspatialite/mod_spatialite matching your SQLite/SQLite-extension-loading build."],"exampleFix":"# before (wrong library target)\nSPATIALITE_LIBRARY_PATH = '/usr/lib/libspatialite.so.7'\n# after (loadable extension module)\nSPATIALITE_LIBRARY_PATH = '/usr/lib/mod_spatialite.so'\n# or: omit the setting and let Django auto-detect","handlingStrategy":"validation","validationCode":"import ctypes, os\nfrom django.conf import settings\npath = getattr(settings, 'SPATIALITE_LIBRARY_PATH', None)\nif path:\n    assert os.path.exists(path), f'SPATIALITE_LIBRARY_PATH missing: {path}'\n    ctypes.CDLL(path)  # raises if not loadable / wrong arch\n    print('OK:', path)","typeGuard":"import os\nfrom django.conf import settings\n\ndef spatialite_library_loads() -> bool:\n    import ctypes\n    p = getattr(settings, 'SPATIALITE_LIBRARY_PATH', None)\n    return bool(p and os.path.exists(p) and _try_cdll(p))\n\ndef _try_cdll(p):\n    try:\n        ctypes.CDLL(p); return True\n    except OSError:\n        return False","tryCatchPattern":null,"preventionTips":["Validate SPATIALITE_LIBRARY_PATH in a Django system check using ctypes.CDLL(path).","Prefer pointing at mod_spatialite.so (loadable module) rather than the base shared lib.","Document the canonical path per OS in the project README."],"tags":["spatialite","configuration","gis","path","backend"],"analyzedSha":"ae25a40be07e8a749edf526df37c93e59d4a22c9","analyzedAt":"2026-08-06T21:46:51.801Z","schemaVersion":2},"datasetVersion":"2026-08-07T03:17:09.362Z"}