Error codes

This page lists every error string the registry/catalog actors emit, what causes it, and how to fix it.

system.packages (SystemPackageRegistryActor)

Error string	Where	Cause	Fix
REGISTRY_SEARCH_INVALID: limit must be an integer from 1 to 100	normalizeLimit	limit argument is not an integer in [1, 100]	Provide limit as integer 1..100, or omit (defaults to 20)
REGISTRY_ROOT_INVALID: registryRoot must be under MATRIX_HOST_HOME (<resolved>)	resolveRegistryRoot	An explicit registryRoot argument resolves outside of $MATRIX_HOST_HOME	Pass a registryRoot inside the Host home, or omit it

system.registry (ServiceRegistryActor)

The registry actor does not currently emit prefixed error strings. Failures are reported through:

• Returning { ok: false } for missing required fields (e.g. blank name for service.register, blank binding/provider for registry.register).
• Returning { ok: true, count: 0 } for resolves that find nothing.
• Throwing only for genuinely exceptional conditions (transport failures outside the actor).

This means error handling is shape-based rather than string-based for system.registry. Callers should check ok and count, not parse error strings.

system.catalog (SystemCatalogActor)

Same pattern as system.registry. The catalog returns { ok: true, ... } even for empty results; entry: null from catalog.resolve means "no such mount." Failures from upstream actors (system.registry, system.runtimes, system.gateway.http) propagate as errors thrown from RequestReply.execute calls and are surfaced by the actor framework, not the catalog actor.

Common upstream failures

When system.catalog calls upstream:

Symptom	Likely cause
catalog.list returns empty catalog: []	system.registry.registry.list returned no claims (no providers heartbeating).
catalog.list throws TIMEOUT	system.registry is not mounted or is wedged.
catalog.search returns webapp entries with stale routePrefix	system.gateway.http route status is stale. The catalog rebuilds on every call, so a re-issue of the search will pick up changes.

CLI surfacing

When invoked through matrix invoke, errors are printed verbatim. For example:

$ matrix invoke system.packages registry.search '{"limit":200}'
Error: REGISTRY_SEARCH_INVALID: limit must be an integer from 1 to 100

The exit code is non-zero. Programmatic callers should match the REGISTRY_* prefix to identify the error class.

See also

• Registry API
• Search

Source: Errors literal-throw at projects/matrix-3/packages/system-catalog/src/SystemPackageRegistryActor.ts:112-137.