Skip to contents

Troubleshooting

Source: vignettes/troubleshooting.qmd

Start with the sitrep 

gdalraster.windows::gdal_sitrep()
gdalraster.windows::gdal_verify()

The default inspects .libPaths()[1]. Pass lib for a custom library, or isolated = TRUE for the package-managed isolated library. The sitrep reports the GDAL runtime tag, build provenance, staleness, Python readiness, already loaded libgdal modules, legacy profile hooks, and a foreign gdalraster package when library(gdalraster) would load a different tree.

library(gdalraster) cannot find the package

Rebuild into the regular user library, or load an isolated install from its library:

gdalraster.windows::gdal_setup()
library(gdalraster)

LoadLibrary reports a missing module

A self-contained build must contain gdalraster.dll, libgdal-*.dll, and the full dependency closure in the same libs/x64 directory:

package_dir <- find.package("gdalraster")
list.files(file.path(package_dir, "libs", "x64"), pattern = "\\.dll$")

Run gdal_update() to rebuild and re-vendor from a complete bundle. Do not add Rtools or another GDAL to PATH as a repair; that defeats package isolation.

Empty Algorithm API or missing drivers

gdal_verify() requires:

  • a non-empty gdal_global_reg_names() result;
  • Arrow, Parquet, HDF5, and netCDF drivers;
  • GEOS and EPSG:4326 resolution; and
  • a successful first Parquet open in a fresh process.

If it fails, compare the runtime and build tags in gdal_sitrep(). A mismatch requires gdal_update(). A matching build with missing drivers indicates a bundle regression and should be reported with the verification output.

Another GDAL is installed

GDAL executables from pixi, conda, OSGeo4W, Rtools, or MSYS2 may remain on the machine. The package’s libs/x64 directory controls dependency resolution while gdalraster.dll loads.

An identically named libgdal already loaded in the process is different: Windows can reuse it by module name. Restart R, load gdalraster first, and inspect gdal_sitrep() for the loaded module path.

Legacy .Rprofile hooks

Version 0.4.0 removes activation and profile-hook APIs. Delete blocks marked:

# >>> gdalraster.windows hook >>>
...
# <<< gdalraster.windows hook <<<

Also remove personal code that calls load_gdal_dll(), activate_gdal_runtime(), or edits GDAL-related environment variables. Rebuild once with gdal_setup() after cleanup.

Locked runtime directory

Windows cannot delete mapped DLLs. gdal_install_runtime(force = TRUE) first tries normal deletion, then moves remaining files into a sibling directory named <gdal_home>.stale-<pid>-<timestamp>. Later installs remove stale directories after locks disappear.

If move-aside also fails, another process holds the file without delete sharing. Close other R sessions and File Explorer previews. PowerToys File Locksmith or Resource Monitor can identify the holder.

Locked gdalraster package

The builder stages the complete replacement before touching the installed package. If the destination DLL is locked, replacement aborts and leaves the old package unchanged. Restart R, ensure gdalraster is not loaded in another session, then rerun the build.

Embedded Python is unavailable

gdal_sitrep() reports whether the managed gdalraster-windows-osgeo-utils.pth points at the current vendored gdalraster/python directory.

For a regular user-library build use:

gdalraster.windows::gdal_enable_python()

When no system CPython is available, core GDAL functionality remains ready, but Python-backed algorithms such as driver gpkg validate cannot run.

Offline and proxy-restricted installation

Transfer a published bundle zip and pass it directly:

gdalraster.windows::gdal_setup(
  local_zip = "C:/Downloads/gdal-bundle-v3.13.2-windows-x64.zip"
)

The installer preserves an embedded manifest when present and otherwise stamps provenance from the requested release information.