Refusal codes

A command that refuses prints a refusal with a code, the field, the measured value, the rule and a suggestion that would pass. Agents and scripts match on the code, so a code never changes silently. mb --help --json lists the codes each command can return; the codes themselves are constants in metrics_book.output.codes.

Exit codes: 0 done, 1 refused or a check failed, 2 used wrongly (flags that conflict, or no project or repository to run in).

Codes

A test fails when this table and metrics_book.output.codes differ. To remove a code, or rename it, change its status here to removed or renamed to <code> and add a line under Changes. Do not delete the row.

Code	Status
svg_too_large	current
svg_not_utf8	current
svg_doctype	current
svg_not_xml	current
svg_root	current
svg_element	current
svg_attribute	current
svg_event_handler	current
svg_external_reference	current
svg_style_url	current
brand.logo.text	current
brand.svg.processing_instruction	current
svg_value	current
svg_use_limit	current
svg_reference_cycle	current
brand.svg.not_clean	current
svg_size_unknown	current
png_invalid	current
png_too_large	current
png_too_small	current
png_unsupported	current
image_format	current
image_missing	current
brand.contrast	current
mark_not_square	current
social_size	current
asset_conflict	current
name_length	current
name_control_character	current
font_unknown	current
locale_invalid	current
currency_unknown	current
week_starts_unknown	current
support_invalid	current
sign_in_line_length	current
sign_in_line_control_character	current
accent_format	current
brand.symlink	current
brand.outside_project	current
brand.source_not_regular	current
unknown_field	current
bad_document	current
stack_invalid	current
palette.cycle	current
palette.unknown	current
palette.invalid	current
palette.role.missing	current
palette.contrast.text	current
palette.contrast.change	current
palette.contrast.mark	current
palette.categorical.lightness	current
palette.categorical.chroma	current
palette.categorical.separation.normal	current
palette.categorical.separation.protan	current
palette.categorical.separation.deutan	current
palette.sequential.order	current
palette.report.missing	current
palette.report.duplicate	current
palette.report.stale	current
palette.report.colour	current
brand.reset_part	current
template.unknown	current
usage	current
filesystem.error	current
usage.conflict	current
usage.root_option	current
usage.unknown_help_topic	current
project.unusable	current
repository.not_found	current
check.e2e_unavailable	current
check.run	current
fmt.run	current
fmt.path_outside	current
init.refused	current
init.name_invalid	current
dev.refused	current
skills.refused	current
skills.unknown_source	current
skills.ambiguous_source	current
template.refused	current
template.differs	current
secrets.refused	current
secrets.value_on_command_line	current
secrets.unknown_name	current
secrets.held_by_host	current
secrets.container	current
secrets.empty_value	current
secrets.format_mismatch	current
secrets.entry_timeout	removed
secrets.no_clipboard	current
secrets.value_too_large	current
secrets.not_set	current
secrets.already_set	current
secrets.core_name	current
secrets.not_generated	current
secrets.run_failed	current
secrets.check	current

Changes

• 2026-10-26: the first listing. The palette codes moved into the same module; their values are unchanged.
• 2026-10-26: usage added. Under --json a usage error (an unknown option, a missing argument, a bad choice) is a refusal with this code; the exit code is 2.
• 2026-10-26: filesystem.error added. A read or write the operating system refuses is a refusal with this code, naming the path and the error, and not a traceback.
• 2026-10-27: secrets.value_too_large added. mb secrets set refuses a value on stdin over 64 KiB after the trailing line break is trimmed; value is the bytes read after trailing line breaks are trimmed, which is not the true size when reading stopped at the limit.
• 2026-10-27: secrets.entry_timeout removed. mb secrets set no longer opens an entry page; with no terminal it reads the value from stdin, as gh secret set does.
• 2026-10-27: usage.unknown_help_topic added. mb help <topic> with a topic that does not exist is a refusal with this code; its suggestion lists the topics.