Error Model

Every error generated by lash includes two components:

• Problem: A plain-English description of what went wrong.
• Suggestion: An actionable step to fix the issue.

Output Formats

Controlled by the LASH_ERROR_FORMAT environment variable or --error-format flag:

Format	Description
human	(default) Clear, conversational messages with source location and suggestion.
json	Single-line compact JSON to stderr. One line per error.
ai	Token-optimized terse format for LLM consumption.

Error Propagation in Chains

When a functional chain fails, lash pinpoints the exact step that caused the failure. In all formats, the full expression and the failing step are identified.

Command failure example:

human:
  `lss -la`.sort()
   ^^^^^^^^
   Command 'lss' not found (exit code 127).
   Did you mean 'ls'? Check your spelling or install the program.

json:
  {"type":"cmd_err","expr":"`lss -la`.sort()","step":"lss -la","code":127,"problem":"command not found","suggest":["ls","less"]}

ai:
  ERR cmd `lss` !found 127 ?ls ?less

Method failure and type mismatch errors follow the same pattern, identifying the failing step index, input data, and expected vs actual types.

Contextual Help

• Invalid Methods: If a user types ls.unknown(), the shell lists the most similar valid methods.
• Permission Issues: Instead of a bare “Permission Denied,” the shell explains which file is restricted and suggests using elevated privileges.

Did-You-Mean Suggestions

When a command or method is not found, the typo-correct plugin (via the error.dispatch hook) provides fuzzy-matched suggestions using Levenshtein distance. The frontend renders an interactive selection UI:

Key	Action
Up/Down	Navigate suggestions, updating prompt
1-9	Jump to numbered suggestion
Enter	Submit selected suggestion
Escape	Dismiss suggestions
Any other	Dismiss suggestions, type that character

Arguments from the original command are preserved in suggestions.