Registry / devops / grpc-rich-error-model

grpc-rich-error-model

library0.0.21jsnpmunverified

Server implementation of the gRPC Rich Error Model for Node.js, providing structured error details like retry info, error info, debug info, and more. Version 0.0.21 is the latest stable release, updated with TypeScript support and matching the gRPC specification. The package fills a gap in the official Node.js gRPC library, which lacks rich error support, unlike gRPC-Web. It integrates seamlessly with @grpc/grpc-js and offers a builder pattern for creating complex error responses.

devops

npm install grpc-rich-error-model

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · GRPC-RICH-ERROR-MO

grpc-rich-error-model

devopsjavascriptv0.0.21

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

createStatusBuilder

✓ import { createStatusBuilder } from 'grpc-rich-error-model'

✗ import { createStatusBuilder } from 'grpc-rich-error-model/build/src/statusBuilder'

Main export for building gRPC status objects with rich error details.

StatusBuilder

✓ import { StatusBuilder } from 'grpc-rich-error-model'

✗ const StatusBuilder = require('grpc-rich-error-model').StatusBuilder

CJS require works, but ESM is recommended for TypeScript projects.

retryInfo

✓ import { retryInfo } from 'grpc-rich-error-model'

Helper function to create retry info details.

Creates a gRPC server that returns a rich error with retry info when a method is called.

import * as grpc from '@grpc/grpc-js'; import { createStatusBuilder } from 'grpc-rich-error-model'; const server = new grpc.Server(); server.addService(myServiceDefinition, { myMethod: (call, callback) => { const status = createStatusBuilder() .withCode(grpc.status.INVALID_ARGUMENT) .withMessage('Invalid argument') .withDetails([ { type: 'type.googleapis.com/google.rpc.RetryInfo', value: { retryDelay: { seconds: 10, nanos: 0 } } } ]) .build(); callback(status); } }); server.bindAsync('0.0.0.0:50051', grpc.ServerCredentials.createInsecure(), () => { server.start(); });

Debug

Known issues

gotchaThe built Status object must be passed to gRPC callback as first argument (error), not as metadata.

fix

Use callback(status) where status is the built object.

affects: *

gotchaRich error details are only supported on the server side; client libraries may ignore them.

fix

Check client library support for rich errors.

affects: *

deprecatedVersion 0.0.18 and below used a different API without builder pattern.

fix

Upgrade to >=0.0.19 and use createStatusBuilder().

affects: <0.0.19

Errors

Common errors & fixes

TypeError: Cannot read properties of undefined (reading 'map')

Details array contains objects without proper type/value structure

fix

Ensure each detail object has type (string) and value (object) properties.

Error: Invalid argument: code must be a gRPC status code number

Passed non-number or invalid code to withCode()

fix

Use grpc.status constants (e.g., grpc.status.INVALID_ARGUMENT).

Upgrade

Version history

0.0.21latest on npm

Audit

Dependencies

@grpc/grpc-jsrequiredPeer dependency for gRPC client/server integration

google-protobufrequiredRequired for protobuf message serialization

Agent activity

8 hits · last 30 days

node

Resources

githubhttps://github.com/markelog/grpc-rich-error-model ↗

packagegrpc-rich-error-model ↗

homepagehttps://github.com/markelog/grpc-rich-error-model#readme ↗