Storage method fields and error codes

When to use

When writing an integration or examining a response, you need to know the exact set of fields, parameter type, role level, VDC (virtual data center) boundary, and meaning of an error code. For step-by-step procedures, see the instructions for viewing pools and for dataset properties; for the model, see Storage pools.

Group summary

Method	Mode	Parameters	Access	What it returns
pool-map	synchronous, from the database	none	Cluster master, Resource Viewer	pools grouped by node_id
pool-map-by-guid	synchronous, from the database	none	not specified in the canonical API documentation	pools grouped by guid, with capacity
pools-list	asynchronous, relayed	nodeId	Cluster master	pools served by the node, with ZFS properties
pools-get	asynchronous, relayed	nodeId, name	Cluster master	full properties of one pool
filesystems-get	asynchronous, relayed	guid	role <= 2, own VDC	dataset properties
filesystems-set	asynchronous, relayed	guid, properties	role <= 2, own VDC	updated dataset properties

Asynchronous methods respond twice: an intermediate {"message": "relayed"} and a final callback from the Storage agent.

Methods

pool-map

A cluster pool map grouped by node_id — the serving node's number. No parameters.

{"jsonrpc": "2.0", "method": "pool-map", "id": "cbf4478c-84b5-45ac-97cd-0390d7190585"}

pool-map-by-guid

A detailed cluster pool map grouped by guid. No parameters.

{"jsonrpc": "2.0", "method": "pool-map-by-guid", "id": "cbf4478c-84b5-45ac-97cd-0390d7190585"}

pools-list

A list of pools served by the node specified in nodeId.

Parameter	Type	Required	Constraints
nodeId	number	yes	range 1–99

{"jsonrpc": "2.0", "method": "pools-list", "params": {"nodeId": 5}, "id": "cbf4478c-84b5-45ac-97cd-0390d7190585"}

pools-get

Detailed information about a pool served by the node specified in nodeId.

Parameter	Type	Required	Constraints
nodeId	number	yes	range 1–99
name	string	yes	pool name

{"jsonrpc": "2.0", "method": "pools-get", "params": {"nodeId": 5, "name": "pool-a"}, "id": "cbf4478c-84b5-45ac-97cd-0390d7190585"}

filesystems-get

ZFS file system properties by disk GUID.

Parameter	Type	Required	Constraints
guid	string | number	yes	length of at least 1, numeric value

{"jsonrpc": "2.0", "method": "filesystems-get", "params": {"guid": "12345"}, "id": "cbf4478c-84b5-45ac-97cd-0390d7190585"}

filesystems-set

Changes ZFS file system properties by disk GUID. Requires the filesystem_options feature to be enabled.

Parameter	Type	Required	Constraints
guid	string | number	yes	length of at least 1, numeric value
properties	object	yes	object containing the ZFS properties to change

{"jsonrpc": "2.0", "method": "filesystems-set", "params": {"guid": "12345", "properties": {"compression": "zstd"}}, "id": "cbf4478c-84b5-45ac-97cd-0390d7190585"}

Pool map fields

Both map methods respond from the vStack Center database. Their sets of fields differ — the columns show which method returns each field.

Field	pool-map	pool-map-by-guid	Meaning
guid	yes	yes	persistent pool identifier
name	yes	yes	pool name
health	yes	yes	pool state; ONLINE for a healthy pool
consuming	yes	yes	the cluster has accepted the pool for active data storage
capacity_pct	yes	yes	pool usage as a percentage
size	yes	yes	usable capacity, excluding the portion allocated to redundancy
node_id	yes	—	number of the node currently serving the pool
nodeid	—	yes	the same field without the underscore in its name
size_raw	—	yes	raw capacity, the sum of pool disk capacities
used	—	yes	space used by data
free	—	yes	remaining usable capacity
provisioned	—	yes	the sum of requested sizes of the pool's datasets
provisioned_pct	—	yes	the ratio of provisioned to usable capacity
scrubbing	—	yes	an integrity check is in progress
resilvering	—	yes	redundancy restoration is in progress
lif	—	yes	the network address at which the pool is accessible

The difference in the node field name (node_id versus nodeid) is a property of the responses, not a documentation typo: a client parsing both methods must recognize both names.

Live method response fields

Node pools: pools-list

The key in the data object is the pool name. Record fields:

allocated  capacity  checkpoint  comment  dedupditto  dedupratio  expandsize
fragmentation  freeing  guid  health  leaked  nodeId  readonly  size

Key field meanings: allocated — space used, capacity — usage as a percentage, fragmentation — fragmentation as a percentage, dedupratio — deduplication ratio, expandsize — available expansion, readonly — read-only mode, freeing — space being freed, leaked — lost blocks.

Pool properties: pools-get

The data object returns the full set of ZFS pool properties:

allocated  altroot  ashift  autoexpand  autoreplace  autotrim  bootfs  cachefile
capacity  checkpoint  comment  compatibility  consuming  dedupditto  dedupratio
delegation  expandsize  failmode  fragmentation  free  freeing  guid  health
leaked  listsnapshots  load_guid  maxblocksize  maxdnodesize  multihost  name
readonly  resilvering  scrubbing  size  tname  version

These include the map fields plus properties of the pool itself: ashift — pool block size; autoexpand, autoreplace, autotrim — automatic expansion, disk replacement, and TRIM; failmode — failure behavior; version — pool version; load_guid — identifier of the current pool load.

Dataset properties: filesystems-get and filesystems-set

The filesystems-get response contains fs_name — the full dataset name, such as pool-a/vm-100-disk-0 — and the properties object. In the filesystems-set response, the dispatcher removes fs_name, leaving only properties. The result.code field also differs. For filesystems-get, the dispatcher sets it to 1; for filesystems-set, the code comes from the Storage agent unchanged.

Fields in properties:

available  checksum  compression  compressratio  context  copies  createtxg
creation  dedup  defcontext  encryption  fscontext  guid  inconsistent  keyformat
keylocation  logbias  logicalreferenced  logicalused  mlslabel  objsetid
pbkdf2iters  pbkdf2salt  primarycache  readonly  redacted  redundant_metadata
refcompressratio  referenced  refreservation  reservation  rootcontext
secondarycache  snapdev  snapshot_count  snapshot_limit  unique  used
usedbychildren  usedbydataset  usedbyrefreservation  usedbysnapshots
useraccounting  volblocksize  volsize  written

Fields most frequently examined:

Field	Meaning
volsize	requested volume size — what the guest system sees
volblocksize	volume block size
used	space the dataset currently occupies in the pool
usedbydataset	the portion of that space used by the data itself
usedbysnapshots	the portion of that space retained by snapshots
snapshot_count	number of dataset snapshots
snapshot_limit	snapshot count limit; -1 means no limit
logicalused	data size before compression
compression	compression algorithm, such as lz4 or zstd
compressratio	gains from compression
dedup	dataset deduplication
encryption	dataset encryption
available	remaining space available to the dataset
readonly	read-only mode
reservation	reserved space
refreservation	reservation for the dataset's own data

Error codes

Code	Message	Methods	Meaning
-403	Access denied	all methods in the group	insufficient role level or a request for another VDC
-21	database error	pool-map	the dispatcher could not read the map from the database
-29	Unable to obtain pool map data	pool-map-by-guid	database error or no pools in the cluster
-23	relay error text	pools-list	the request was not sent to the node
-24	nodeId is not present in the cluster	pools-list	no node with this number exists in the cluster
-25	Pool is not present on the requested node	pools-list	the node responded without pool data
-33	relay error text	pools-get	the request was not sent to the node
-34	nodeId is not present in the cluster	pools-get	no node with this number exists in the cluster
-35	Pool is not present on the requested node	pools-get	the node responded without data for the pool
-57	param guid has bad value	filesystems-get	invalid guid or a relay failure
-58	Dataset does not exist at users scope	filesystems-get	the dataset does not exist or belongs to another VDC
-53	Unable to locate the dataset	filesystems-get	the dataset row in the dispatcher's database has an empty name
-54	Unable to locate the pool of the dataset	filesystems-get	the dataset's pool has no serving node assigned
-86	param guid has bad value	filesystems-set	invalid guid or a relay failure
-87	Filesystems methods has not been enabled	filesystems-set	the filesystem_options feature is disabled in the cluster
-88	Dataset does not exist at users scope	filesystems-set	the dataset does not exist or belongs to another VDC
-83	Unable to locate the dataset	filesystems-set	the dataset row in the dispatcher's database has an empty name
-84	Unable to locate the pool of the dataset	filesystems-set	the dataset's pool has no serving node assigned

The parameter validator rejects an invalid nodeId. The client receives -32602 Invalid params before the request reaches the method handler.

Two pairs of codes each cover two different cases: -57 and -86 cover an invalid guid and a relay failure; -58 and -88 cover a missing dataset and a dataset belonging to another VDC. The latter pair is intentional: the existence of a dataset in another VDC is not disclosed.

UI column mapping

The ZFS pools table on the Storage Resources tab reflects the pool map fields. The UI defines the exact column mapping; the fields below contain the corresponding values.

Column	Map field
GUID	guid
Name	name
Health	health
Consuming	consuming
Scrubbing	scrubbing
Resilvering	resilvering
Current node	nodeid
Capacity (RAW)	size_raw and capacity_pct

Example

An end-to-end sequence: retrieve the map, select a pool from it, and query its dataset properties.

{"jsonrpc": "2.0", "method": "pool-map-by-guid", "id": "cbf4478c-84b5-45ac-97cd-0390d7190585"}

Take "nodeid": 5 and "name": "pool-a" from the response. Request the pool properties:

{"jsonrpc": "2.0", "method": "pools-get", "params": {"nodeId": 5, "name": "pool-a"}, "id": "cbf4478c-84b5-45ac-97cd-0390d7190585"}

Then request the properties of a disk dataset in this pool:

{"jsonrpc": "2.0", "method": "filesystems-get", "params": {"guid": "12345"}, "id": "cbf4478c-84b5-45ac-97cd-0390d7190585"}

Expected result: in the final response, fs_name starts with pool-a/ — the dataset is indeed in the requested pool.