Known issues

libnetcdf not properly installed

If you see the following error,

ERROR: LoadError: LoadError: libnetcdf not properly installed. Please run Pkg.build("NCDatasets")

you can try to install netcdf explicitly with Conda:

using Conda
Conda.add("libnetcdf")

NetCDF: Not a valid data type or `_FillValue` type mismatch

Trying to define the _FillValue, procudes the following error:

ERROR: LoadError: NCDatasets.NetCDFError(-45, "NetCDF: Not a valid data type or _FillValue type mismatch")

The error could be generated by a code like this:

using NCDatasets, DataStructures
# ...
tempvar = defVar(ds,"temp",Float32,("lonc","latc","time"), attrib = OrderedDict(
    "_FillValue" => -9999.))

using NCDatasets
# ...
tempvar = defVar(ds,"temp",Float32,("lonc","latc","time"), fillvalue = -9999.)

In fact, _FillValue must have the same data type as the corresponding variable. In the case above, tempvar is a 32-bit float and the number -9999. is a 64-bit float (aka double, which is the default floating point type in Julia). It is sufficient to convert the value -9999. to a 32-bit float -9999.f0 (or Float32(-9999.)).

Defining the attributes `_FillValue`, `add_offset`, `scale_factor`, `units` and `calendar`

An error like Cannotconvertan object of type Missing (or similar) is generated by code like this:

v = defVar(ds,"var_with_all_missing_data",Float32,("lon",))
v.attrib["_FillValue"] = fv
v[1] = missing

This produces the following error:

ERROR: LoadError: MethodError: Cannot `convert` an object of type Missing to an object of type Float32
Closest candidates are:
  convert(::Type{T}, ::T) where T<:Number at number.jl:6
  convert(::Type{T}, ::Number) where T<:Number at number.jl:7
  convert(::Type{T}, ::Base.TwicePrecision) where T<:Number at twiceprecision.jl:250
  ...
Stacktrace:
 [1] fill!(::SubArray{Float32,1,NCDatasets.CFVariable{Float32,1,NCDatasets.Variable{Float32,1},NCDatasets.Attributes},Tuple{UnitRange{Int64}},false}, ::Missing) at ./multidimensional.jl:865
 [2] copyto! at ./broadcast.jl:871 [inlined]
 [3] materialize!(::SubArray{Float32,1,NCDatasets.CFVariable{Float32,1,NCDatasets.Variable{Float32,1},NCDatasets.Attributes},Tuple{UnitRange{Int64}},false}, ::Base.Broadcast.Broadcasted{Base.Broadcast.DefaultArrayStyle{0},Nothing,typeof(identity),Tuple{Base.RefValue{Missing}}}) at ./broadcast.jl:822

One should use define the _FillValue (and similar attributes like add_offset, scale_factor, units and calendar affecting the type of the data) in the call of defVar:

using DataStructures
v = defVar(ds,"var_with_all_missing_data",Int32,("lon",), fillvalue = fv, attrib = OrderedDict(
    "scale_factor" => 0.1,
    "add_offset" => 0.1
    ))

This change was introduced in NCDatasets version 0.10

Mutiple versions of HDF5 or NetCDF libraries

Having outdated versions of HDF5 or NetCDF libraries installed can be an issue on Windows if they are included in the system PATH environement variable. It is advised to adapt the system PATH to remove the locations containing these libraries.

Corner cases

An attribute representing a vector with a single value (e.g. [1]) will be read back as a scalar (1) (same behavior in python netCDF4 1.3.1).
NetCDF and Julia distinguishes between a vector of chars and a string, but both are returned as string for ease of use, in particular an attribute representing a vector of chars ['u','n','i','t','s'] will be read back as the string "units".
An attribute representing a vector of chars ['u','n','i','t','s','\0'] will also be read back as the string "units" (issue #12).
While reading a NetCDF time variable, the dates are converted using the Julia's DateTime (based on the proleptic Gregorian calendar following the ISO 8601 standard) when possible. When data is written to a NetCDF file (without specifying the calendar), the dates are saved using the default calendar of the NetCDF CF convention (the mixed Julian/Gregorian calendar, called "standard") when possible. It is recommended that the time origin specified by the units is after 15 October 1582 in which case the mixed Julian/Gregorian calendar is identical to the proleptic Gregorian calendar.