Errors

View as Markdown

M-Files Server reports every failure of its own with one of two gRPC status codes:

Other status codes come from the gRPC layer, not from M-Files logic:

The error trailers

A call that fails with UNKNOWN has two trailers:

Each RPCErrorInfo has error_code (an HRESULT as a signed 32-bit integer), description (extra detail, often empty), and file and line (the server source location). The entries run from the original cause (first) to the top-level error (last); the status message describes the last one. The same code usually repeats as the error passes up through the server. Example for an unknown vault GUID at login:

Status message: The specified document vault does not exist. followed by the Vault ID line.

When the stack is too large for the trailer limit, the server drops entries from the middle and shortens long texts; the first and the last entries are kept.

Which code to act on. Test whether a code you handle appears anywhere in the stack. The last entry is the top-level error and the most stable choice; the first one names the original cause, which is sometimes more specific (for "access denied", the first entry says whether vault-level or object-level rights were missing) and sometimes only a free-text carrier (0x80040120). Do not parse the message text: it can change between versions. A missing permission does not always produce an error: Permissions shows when the server answers "Not found." or leaves items out instead.

The text trailer and file/line are diagnostics that include server source file names and the server version. Log them; do not show them to end users.

Decoding in Python

The samples' helper decodes the stack into a list of entries and their unsigned codes:

self.long_message: str = trailers.get(ERROR_TEXT_KEY, b"").decode("utf-8", "replace")
self.stack = list(structs_pb2.RPCErrorInfoArray.FromString(
    trailers.get(ERROR_STACK_KEY, b"")).value)
self.codes = [entry.error_code & 0xFFFFFFFF for entry in self.stack]  # cause first
# The top-level error, skipping entries that only pass the error on.
self.hresult: Optional[int] = next(
    (code for code in reversed(self.codes) if code != E_PASS_THROUGH),
    self.codes[-1] if self.codes else None)

Source: python/mfiles_client.py

A code is often written as unsigned hex (0x800407E4) and sometimes as a signed integer (-2147219484); code & 0xFFFFFFFF converts the signed value to the unsigned one. The error handling guide shows the same in C# and Go.

Common error codes

Observed against a server unless marked "code only". The message is the English status message.