DOCS · GUIDE

Error handling

GDAL reports problems through an error stack, not exceptions. Read it after suspicious calls, and check the decoder table before filing an issue.

The error-state API

after a failing call

const ds = await Gdal.open("/opfs/broken.tif");   // may come back null/invalid

const msg  = await Gdal.getLastErrorMsg();
const code = await Gdal.getLastErrorNo();
const type = await Gdal.getLastErrorType();   // none / warning / failure
await Gdal.errorReset();                      // clear before the next operation

The VSI layer (file I/O) keeps its own state: Gdal.vsiGetLastErrorMsg(), vsiGetLastErrorNo(), vsiErrorReset(). Wrap conversions in a helper that snapshots both on failure and you'll never debug blind.

Decoding common errors

MESSAGE	WHAT IT ACTUALLY MEANS
`Pointer 'hDS' is NULL`	A previous step failed (usually the open or the output creation) and you used the result anyway. Check `getLastErrorMsg()` right after the first call (issues #68, #77).
`ERROR 4: Failed to create … No such file or directory`	The output directory doesn't exist. `await Module.FS.mkdirTree(dir)` first (issue #69).
`Cannot open TIFF … missing codec JPEG/ZSTD`	Pre-codec build. Fixed since the April 2026 codec PRs; v3 bundles JPEG, ZSTD and LERC (issues #103, #99).
`Unknown option name '-…'`	On v2: the wrapper's parser didn't know the switch (#53, #95). On v3 options go to GDAL's own parsers. Check spelling against the GDAL docs.
`wasm … unsupported MIME type`	Your server serves `.wasm` without `application/wasm`. Add the MIME type (issue #54).
`Recode from CP936 to UTF-8 failed`	Source file in a legacy encoding (common with DXF). Re-encode to UTF-8, or set the driver's encoding option (issue #39).
`Can't transform coordinates … no source SRS`	The input has no CRS. Inspect via `ds.info(['-json'])`, then pass `-s_srs` explicitly (issue #65).

v2: log & error handlers

v2.6.0+

initGdalJs({
  logHandler:   (msg, type) => myLog(type, msg),
  errorHandler: (msg, type) => myErr(type, msg),
});

On the v2 line, stderr/stdout streams are captured by handlers passed at init (added for issue #63). In v3, prefer the structured error-state API above.

← PREVVirtual file system NEXT →Optimization