---
name: bash_handle_error
kind: function
lang: bash
domain: shell
version: "1.0.0"
purity: impure
signature: "handle_error(error_code: string, error_description: string, [solution: string]) -> exit_code"
description: "Muestra un box de error formateado con contexto del fallo: script, linea, funcion, directorio y usuario. Registra en log."
tags: [bash, error, handler, box, formatted, context, pendiente-usar]
uses_functions: [bash_colors_bash_shell, bash_log_bash_shell]
uses_types: []
returns: []
returns_optional: false
error_type: "error_go_core"
imports: []
params:
  - name: error_code
    desc: "codigo identificador del error, ej: BUILD_FAILED, DB_CONNECTION_ERROR"
  - name: error_description
    desc: "descripcion legible del error para mostrar al usuario"
  - name: solution
    desc: "solucion sugerida; opcional; si se provee se muestra en seccion separada"
output: "box de error formateado en stdout con contexto (script, linea, funcion, directorio, usuario) + registro en log; retorna exit code 1"
tested: false
tests: []
test_file_path: ""
file_path: "bash/functions/shell/bash_handle_error.sh"
source_repo: "https://gitea-dgg044oo04woo4ggcsws4gk0.organic-machine.com/egutierrez/DevLauncher.git"
source_license: "MIT"
source_file: "scripts/lib/common.sh"
---

## Ejemplo

```bash
source bash/functions/shell/bash_handle_error.sh

build_project() {
    go build ./... || handle_error "BUILD_FAILED" \
        "La compilacion del proyecto fallo" \
        "Ejecuta 'go mod tidy' y verifica que todas las dependencias esten instaladas"
}

connect_db() {
    psql "$DB_URL" -c '\q' 2>/dev/null || handle_error "DB_CONNECTION_ERROR" \
        "No se pudo conectar a la base de datos"
}
```

## Notas

El box usa caracteres unicode de `bash_colors` (BOX_TL, BOX_H, etc.) para el borde en rojo. La informacion de contexto se extrae de `BASH_SOURCE`, `BASH_LINENO` y `FUNCNAME` con offset 2 para apuntar al caller del caller.

La funcion siempre retorna 1, permitiendo usarla como `cmd || handle_error ...` en pipelines de error.

Usa `bash_colors` y `bash_log` como dependencias. Sourcea ambas automaticamente al cargarse.