Skip to content

What rtb-error does not do

Every item here is a real limit of the crate as shipped in 0.6.3, not a roadmap. Where there is a workaround it is named.

It does not log

There is no logger, no tracing integration, and no way to ask the crate to record anything. Errors are rendered once at the process edge and that is the crate's entire output. In particular, a footer closure that panics is caught and dropped with no complaint — nothing anywhere reports the suppression.

If you want an error recorded as well as displayed, do it at your own boundary, where you already hold the Report.

It does not decide the process exit code for you

exit_code_of reads a code back; nothing applies it. There is no main wrapper, no Application::run, no #[rtb_error::main]. A tool that returns miette::Result<()> from main exits 1 on every error regardless of what was attached — attaching an exit code only matters if your main returns std::process::ExitCode and reads it. See Set the process exit code.

The exit code does not survive being boxed into Error::Other

exit_code_of is a downcast. Attach a code, wrap the result in rtb_error::Error::Other(Box::new(coded)), and the code is gone — the report now downcasts to Error, not to ExitCoded, and the boundary falls back to its default. Report::wrap_err is fine; Error::Other is not. Attach the code at the outermost layer.

It cannot recover a hook that something else installed first

miette's hook is a process-global OnceLock, filled by whichever comes first: your install_report_handler call, an explicit miette::set_hook elsewhere, or the construction of the very first miette::Report anywhere in the process. Lose that race and this crate's handler — and therefore the footer — never runs, silently. There is no override, no reinstall, and no way to query whether it happened.

The only mitigation is ordering: install as the first statement of main. A dependency that builds a Report during its own initialisation wins, and there is nothing to be done about it from here.

It does not adapt rendering to the terminal the way miette does

Installing this crate's handler replaces miette's MietteHandler with a GraphicalReportHandler, which loses three pieces of environment detection: the wrap width becomes a fixed 200 columns instead of the terminal's, NO_GRAPHICS no longer switches to the narratable renderer, and terminal hyperlinks are emitted whether or not the terminal supports them. Colour and ASCII/Unicode fallback still adapt. There is no configuration for any of this.

If your tool needs terminal-accurate rendering or the narratable renderer for accessibility, install your own miette hook and do not call install_report_handler. You lose the footer; nothing else in this crate depends on the hook.

No formatting hooks, no per-severity footers, no way to suppress the footer for one diagnostic from the call site. The closure sees nothing about the diagnostic being rendered — it takes no arguments. Returning an empty string suppresses the footer for that render, and that is the only conditional behaviour available.

Error is not Clone, not PartialEq, and not a domain error type

std::io::Error is neither Clone nor PartialEq, and Box<dyn Diagnostic> cannot be either, so Error is neither. Compare on the diagnostic code or on the Display string in tests.

More importantly, Error is not somewhere to add your own variants. It is #[non_exhaustive], its variants describe application scaffolding, and it will not grow one for your domain. Define your own enum.

There is no no_std build and no feature flags

The crate declares no [features] table at all. miette's fancy feature is always compiled in, along with the terminal-detection dependencies that come with it, and hook needs std for OnceLock, RwLock, std::panic and thread-locals. There is no lighter configuration to select.

It does not redact anything

An error's Display output is printed verbatim, including whatever was interpolated into it. Error::Config(String) will happily render a configuration value containing a credential. Sanitise before constructing the error — the toolkit's rtb-redact crate exists for that job, and this crate does not call it.

It does not install anything on Drop or at process start

Nothing happens implicitly. No constructor runs before main, no static initialiser installs a hook, no Drop impl flushes anything. Every effect this crate has is the result of a function you called.