Errors & exceptions

The error taxonomy is how your component tells which subsystem failed — config, schema validation, messaging, credentials, parameters, or streaming — and decides whether to recover or abort. Each SDK exposes the same set of failure modes, but in its own idiomatic shape, so the type you catch differs by language even when the underlying cause is identical.

There is no single, unified error type across the four languages. Only Rust unifies everything into one enum; TypeScript unifies the core subsystems only; Java and Python use a distinct exception class per subsystem.

How errors are shaped per language

Java

A small set of subsystem exceptions in com.mbreissi.edgecommons. Some are checked (the compiler forces a try/catch or throws), some are unchecked (RuntimeException).

// package com.mbreissi.edgecommons.*
class ConfigurationException extends Exception                 // CHECKED — config.ConfigurationException
class ConfigurationValidator.ConfigurationValidationException  // CHECKED — nested static in config.ConfigurationValidator
        extends Exception
class CredentialException extends RuntimeException             // unchecked — credentials.CredentialException
class ParameterException extends RuntimeException              // unchecked — parameters.ParameterException
class EdgeStreamException extends RuntimeException {             // unchecked — streaming.EdgeStreamException
    EdgeStreamException(int code, String message);
    int code();                                               // the underlying esl_status value
    // constants mirroring esl_status:
    //   OK=0, ERR_CONFIG=1, ERR_IO=2, ERR_CORRUPT=3, ERR_FULL=4,
    //   ERR_UNKNOWN_STREAM=5, ERR_SINK=6, ERR_PANIC=7, ERR_INVALID_ARG=8
}

CLI and builder preconditions throw the standard IllegalArgumentException (e.g. unknown --platform / --transport, the unsupported -m/--mode flag) and IllegalStateException (builder precondition violations).

Python

Subsystem Exception subclasses, each exported from its package.

edgecommons.credentials

class CredentialError(Exception): ...                  # message-only

# edgecommons.parameters
class ParameterError(Exception): ...                   # message-only

# edgecommons.streaming
class EdgeStreamError(Exception):
    def __init__(self, code: int, message: str | None = None)
    # instance attributes: .code (int), .message

# edgecommons.validation.configuration_validator
class ConfigurationValidationException(Exception):
    def __init__(self, message: str, validation_errors: list | None = None)
    # instance attribute: .validation_errors

Python has no dedicated config-load exception class. Config-load failures surface as the built-in ValueError, as ConfigurationValidationException, or as a propagated stdlib exception. Using an accessor before the runtime is initialized raises RuntimeError("EdgeCommons not properly initialized").

Rust

One library-wide error enum plus a Result alias in edgecommons. Fallibility is encoded in the return type — there are no separate per-subsystem error types.

// edgecommons
pub type Result<T> = std::result::Result<T, EdgeCommonsError>;

#[derive(Debug, thiserror::Error)]
pub enum EdgeCommonsError {
    Cli(String),         // CLI parsing / contract violation
    Config(String),      // config loading / shape
    Validation(String),  // JSON-schema validation failure
    Messaging(String),
    Metrics(String),
    Ipc(String),         // Greengrass IPC
    Streaming(String),   // `streaming` feature
    Credentials(String), // `credentials` feature
    Parameters(String),  // `parameters` feature
    UnsValidation { code: UnsValidationCode, detail: String },  // UNS topic build/validate
    Command(String),                                             // commands() inbox verb registration
    ReservedTopic(String),                                       // reserved-class publish guard
    RequestTimeout { topic: String, secs: f64 },                 // request() deadline fired
    Facade(String),        // data()/events()/app() body-contract violation
    Io(std::io::Error),    // #[from] — auto-converts via `?`
    Json(serde_json::Error), // #[from] — auto-converts via `?`
}

EdgeCommonsError is Send + Sync; constructing or matching on it cannot panic. The #[from] on Io and Json means stdlib I/O and serde_json errors convert into a EdgeCommonsError automatically through the ? operator. Two subsystem variants complete the set (16 in all): Command — a commands() verb-registration error (a verb collides with a built-in, a delegated verb, or an already-registered one) — and Facade, the data()/events()/app() body-contract rejection the facades cannot default away (a missing signal.id, an empty samples/evt type/app name, …), distinct from UnsValidation (topic shape) and Messaging (transport).

TypeScript

Two families. The core subsystems share one tagged EdgeCommonsError; credentials, parameters, and streaming are standalone Error subclasses that are not part of the tag union.

// @edgecommons/edgecommons
type EdgeCommonsErrorKind =
  | "Cli" | "Config" | "Validation"
  | "Messaging" | "Metrics" | "Ipc"
  | "Io" | "Json";                       // NOTE: no Streaming/Credentials/Parameters

class EdgeCommonsError extends Error {
  readonly kind: EdgeCommonsErrorKind;            // this.name === `EdgeCommonsError(${kind})`
  // static factories: EdgeCommonsError.cli / config / validation / messaging /
  //                   metrics / ipc / io / json
}

// separate Error subclasses (NOT covered by EdgeCommonsErrorKind):
class CredentialError extends Error {}                 // this.name = "CredentialError"
class ParameterError extends Error {}                  // this.name = "ParameterError"
class EdgeStreamError extends Error {                     // this.name = "EdgeStreamError"
  readonly code: number;                               // the underlying esl_status value
}
class UnsValidationError extends Error {               // UNS topic build/validate failure
  readonly code: UnsValidationCode;                    // machine-readable §2.2 code
}
class ReservedTopicError extends Error {}              // reserved-class publish guard
class RequestTimeoutError extends Error {}             // request() deadline fired

Because EdgeCommonsErrorKind omits Streaming/Credentials/Parameters, a check like e.kind === "Streaming" will never match — those failures are the separate classes above. Use instanceof EdgeStreamError / instanceof CredentialError / instanceof ParameterError instead.

Where each subsystem’s failure surfaces

The same logical failure maps to a different type in each SDK. Read across a row to translate.

Subsystem failure	Java	Python	Rust	TypeScript
CLI / arg validation	IllegalArgumentException	ValueError	EdgeCommonsError::Cli	EdgeCommonsError kind "Cli"
Config load	ConfigurationException (checked)	ValueError / propagated	EdgeCommonsError::Config	EdgeCommonsError kind "Config"
Schema validation	ConfigurationValidationException (checked)	ConfigurationValidationException	EdgeCommonsError::Validation	EdgeCommonsError kind "Validation"
Messaging	standard exception (no dedicated class)	standard exception (no dedicated class)	EdgeCommonsError::Messaging	EdgeCommonsError kind "Messaging"
Metrics	standard exception (no dedicated class)	standard exception (no dedicated class)	EdgeCommonsError::Metrics	EdgeCommonsError kind "Metrics"
Greengrass IPC	standard exception (no dedicated class)	standard exception (no dedicated class)	EdgeCommonsError::Ipc	EdgeCommonsError kind "Ipc"
UNS topic build/validate	UnsValidationException (+getCode())	UnsValidationError (+.code)	EdgeCommonsError::UnsValidation { code, .. }	UnsValidationError (+.code)
Reserved-class publish	ReservedTopicException	ReservedTopicError	EdgeCommonsError::ReservedTopic	ReservedTopicError
Request deadline	java.util.concurrent.TimeoutException (exceptional future)	RequestTimeoutError (raised by Iou.get())	EdgeCommonsError::RequestTimeout	RequestTimeoutError (rejected promise)
Credentials	CredentialException	CredentialError	EdgeCommonsError::Credentials	CredentialError
Parameters	ParameterException	ParameterError	EdgeCommonsError::Parameters	ParameterError
Streaming	EdgeStreamException (+code())	EdgeStreamError (+.code)	EdgeCommonsError::Streaming (code discarded)	EdgeStreamError (+.code)
I/O · JSON	JDK IOException etc.	stdlib exceptions	EdgeCommonsError::Io / EdgeCommonsError::Json	EdgeCommonsError kind "Io" / "Json"

The UNS validation errors carry the machine-readable code set pinned in uns-test-vectors/ (EMPTY_TOKEN, BAD_CHAR, DEPTH_EXCEEDED, … — see the UNS API reference), identical across languages.

When each is thrown

Java

• ConfigurationException — thrown by ConfigManagerFactory.create(...) when no configuration is found, or when a ConfigManager cannot be created. It is not thrown by ConfigManager itself.
• ConfigurationValidationException — thrown by ConfigurationValidator.validate(JsonObject) when the config violates the canonical JSON schema. It is fail-closed: a missing schema resource on the classpath also throws (it does not silently pass).
• CredentialException — vault open/decrypt failures: a wrong KEK, tampered data, an unsupported vault format, or corrupt JSON. Messages never include secret or key material.
• ParameterException — parameter resolution/decryption failures (the parameters subsystem reuses the credentials vault as an encrypted cache).
• EdgeStreamException — any non-zero esl_status from the native edgestreamlog engine; inspect code() (e.g. ERR_UNKNOWN_STREAM, ERR_CONFIG, ERR_FULL) to branch.

Python

• ConfigurationValidationException — raised by ConfigurationValidator.validate(config) and validate_section(...) on a schema violation; fail-closed when jsonschema or the schema resource is missing. A None config raises the built-in ValueError instead.
• CredentialError — vault failures (wrong KEK, tamper, unsupported format, corrupt data).
• ParameterError — parameter resolution/decryption failures.
• EdgeStreamError — native streaming failures; check .code (e.g. ERR_UNKNOWN_STREAM is 5, ERR_CONFIG is 1). It is also raised with .code == -1 when the native streaming wheel is not installed.
• ValueError — None/empty inputs (validation, an empty component name in the builder, and other argument checks).
• RuntimeError — "EdgeCommons not properly initialized" when an accessor is used before init.

Rust

Every fallible call returns Result<T, EdgeCommonsError>; match on the variant to tell subsystems apart.

• EdgeCommonsError::Cli — CLI parsing or contract violations (unknown platform/transport, etc.).
• EdgeCommonsError::Config — config loading / shape problems.
• EdgeCommonsError::Validation — JSON-schema validation failures.
• EdgeCommonsError::Messaging / EdgeCommonsError::Metrics / EdgeCommonsError::Ipc — the respective subsystem failed; messaging() itself returns Err(EdgeCommonsError::Messaging(...)) when the transport is unwired.
• EdgeCommonsError::Streaming / EdgeCommonsError::Credentials / EdgeCommonsError::Parameters — the matching feature-gated subsystem failed (these variants exist only when the corresponding cargo feature is enabled).
• EdgeCommonsError::Io / EdgeCommonsError::Json — propagated stdlib I/O or serde_json errors, converted automatically by ?.

TypeScript

• EdgeCommonsError (kind "Validation") — thrown by validate(...) on a schema violation.
• EdgeCommonsError (kind "Cli" / "Config") — CLI/arg and config-load problems.
• EdgeCommonsError (kind "Messaging" / "Metrics" / "Ipc") — the respective subsystem failed; messaging() throws EdgeCommonsError.messaging(...) when the transport is unwired, while metrics() returns the (always-wired) metric service.
• EdgeCommonsError (kind "Io" / "Json") — I/O and JSON failures.
• CredentialError — vault failures (wrong KEK, tamper, unsupported format).
• ParameterError — parameter resolution/decryption failures.
• EdgeStreamError — native streaming failures; check .code. The helper translate(e) parses a native esl:<code>:<message> string into a EdgeStreamError.

The streaming status code

Streaming is the one place that carries a numeric status (esl_status from the native edgestreamlog engine) — but only three of the four SDKs preserve it.

Java

EdgeStreamException.code() returns the int, and named constants are exposed (EdgeStreamException.ERR_FULL, ERR_UNKNOWN_STREAM, …) so you can branch on a name.

EdgeStreamException ex = assertThrows(EdgeStreamException.class, () -> svc.stats("nope"));
assertEquals(EdgeStreamException.ERR_UNKNOWN_STREAM, ex.code());   // 5

Python

EdgeStreamError.code holds the int, but no named ERR_* constants are exposed — compare against the literal integers (or declare your own).

from edgecommons.streaming import EdgeStreamError

with pytest.raises(EdgeStreamError) as ei:
    svc.stats("nope")
assert ei.value.code == 5     # ERR_UNKNOWN_STREAM — no named constant in edgecommons.streaming

Rust

The code is discarded. Streaming failures stringify into EdgeCommonsError::Streaming(String), so a Rust caller can read the message but cannot branch on the numeric esl_status.

// streaming errors funnel into EdgeCommonsError::Streaming(e.to_string()) — no numeric code is retained
if let Err(edgecommons::EdgeCommonsError::Streaming(msg)) = result {
    eprintln!("streaming failed: {msg}");
}

TypeScript

EdgeStreamError.code holds the int (no named constants).

import { EdgeStreamError } from "@edgecommons/edgecommons";

// e was thrown by a streaming call (or produced by translate(...))
expect((e as EdgeStreamError).code).toBe(5);   // ERR_UNKNOWN_STREAM

Optional subsystems return empty, they do not throw

Credentials, parameters, and streaming are opt-in: when the matching config section is absent (and, in Rust, the matching cargo feature is enabled), the accessor returns an empty value rather than throwing. Always check before use.

Java

getStreams(), getCredentials(), and getParameters() return null when the section is absent. getMessaging() and getMetrics() return the wired subsystem.

var creds = gg.getCredentials();
if (creds == null) {
    // no `credentials` config section — feature is off
} else {
    var secret = creds.get("db-password");
}

Python

get_streams(), get_credentials(), and get_parameters() return None when the section is absent.

creds = gg.get_credentials()
if creds is None:
    pass   # no `credentials` config section — feature is off
else:
    secret = creds.get("db-password")

Rust

credentials() and parameters() return Option; streams() is gated behind the streaming feature. By contrast messaging() returns a Result and yields Err(EdgeCommonsError::Messaging(...)) when the transport is unwired.

match gg.credentials() {
    None => { /* no `credentials` config section — feature is off */ }
    Some(creds) => { let _secret = creds.get("db-password")?; }
}

TypeScript

streams(), credentials(), and parameters() return undefined when the section is absent. By contrast messaging() throws EdgeCommonsError.messaging(...) when the transport is unwired.

const creds = gg.credentials();
if (creds === undefined) {
  // no `credentials` config section — feature is off
} else {
  const secret = await creds.get("db-password");
}

Handling errors

A minimal, idiomatic handler in each language — catch the validation error to abort startup, and branch on the streaming status code where it is available.

Java

import com.mbreissi.edgecommons.config.ConfigurationValidator;
import com.mbreissi.edgecommons.config.ConfigurationValidator.ConfigurationValidationException;
import com.mbreissi.edgecommons.streaming.EdgeStreamException;

// Checked: the compiler forces you to handle (or declare) this one.
try {
    ConfigurationValidator.validate(config);            // JsonObject
} catch (ConfigurationValidationException e) {
    log.error("config rejected: {}", e.getMessage());   // lists each schema violation
    throw new IllegalStateException("cannot start", e); // abort startup
}

// Unchecked, code-bearing.
try {
    var stats = gg.getStreams().stats("telemetry");
} catch (EdgeStreamException e) {
    if (e.code() == EdgeStreamException.ERR_FULL) {
        // durable buffer is full — back off and retry later
    } else {
        throw e;
    }
}

Python

from edgecommons.validation.configuration_validator import (
    ConfigurationValidator,
    ConfigurationValidationException,
)
from edgecommons.streaming import EdgeStreamError

try:
    ConfigurationValidator.validate(config)
except ConfigurationValidationException as e:
    # e.validation_errors carries the individual violations
    raise SystemExit(f"config rejected: {e}")

try:
    stats = gg.get_streams().stats("telemetry")
except EdgeStreamError as e:
    if e.code == 4:        # ERR_FULL — no named constant exported
        pass               # back off and retry later
    else:
        raise

Rust

use edgecommons::{EdgeCommonsBuilder, EdgeCommonsError};

let gg = match EdgeCommonsBuilder::new("com.example.MyComponent")
    .args(std::env::args_os())
    .build()
    .await
{
    Ok(gg) => gg,
    Err(EdgeCommonsError::Cli(msg)) => {
        eprintln!("bad CLI args: {msg}");
        std::process::exit(2);   // the app decides to exit — the library never does
    }
    Err(EdgeCommonsError::Config(msg)) | Err(EdgeCommonsError::Validation(msg)) => {
        eprintln!("config rejected: {msg}");
        std::process::exit(1);
    }
    Err(e) => {
        eprintln!("startup failed: {e}");
        std::process::exit(1);
    }
};

TypeScript

import { EdgeCommonsError, EdgeStreamError } from "@edgecommons/edgecommons";

try {
  validate(config);
} catch (e) {
  if (e instanceof EdgeCommonsError && e.kind === "Validation") {
    console.error(`config rejected: ${e.message}`);
    process.exit(1);            // the app decides to exit — the library never does
  }
  throw e;
}

try {
  const stats = await gg.streams()?.stats("telemetry");
} catch (e) {
  // streaming is a separate class, NOT EdgeCommonsError kind "Streaming"
  if (e instanceof EdgeStreamError && e.code === 4 /* ERR_FULL */) {
    // back off and retry later
  } else {
    throw e;
  }
}

Process exit and SIGTERM

Whether a failure (or shutdown) ends the OS process differs sharply across the SDKs. This matters when a supervisor (the Nucleus, a container runtime, Kubernetes) watches the exit code.

Exit behavior is not uniform

• Java calls System.exit(0) in exactly one place: the -h/--help usage path, after printing help. Its SIGTERM/shutdown hook deliberately does not call System.exit — the JVM exits 0 once the hooks finish.
• Python’s library error types do not exit, but the EdgeCommons orchestrator does call sys.exit(0) from its SIGTERM handler. Net effect: on SIGTERM, Python exits the process and Java does not.
• Rust and TypeScript never exit the process from the library — they return or throw and let your application decide (the handler examples above call process::exit / process.exit explicitly, in app code).

Note

Whatever the exit path, always unsubscribe and handle SIGTERM cleanly before exit — a leaked subscription or thread can trip the shared-connection quota on the next run.

See also

Entry point & builderThe accessors that surface these errors, and the opt-in null/None/Option/undefined contract.

Configuration referenceThe config sources and JSON-schema validation that raise ConfigurationException / ConfigurationValidationException.

Streaming referenceThe telemetry-streaming subsystem behind EdgeStreamException / EdgeStreamError and the esl_status code.