Troubleshooting

Esta página agrupa los síntomas más reportados por integradores y operadores de tecsas3-cli con la acción correctiva mínima para cada uno. Cuando un fallo no aparezca aquí, ejecuta primero tecsas3 util ping y tecsas3 auth whoami para acotar el problema a red, perfil o autorización.

Antes de depurar, asegúrate de usar la última versión estable:

pip install -U tecsas3-cli
tecsas3 --version

Tabla de síntomas → fixes

Síntoma	Fix
`401 Unauthorized`	`tecsas3 auth login` o `tecsas3 auth use <profile>`
`403 Forbidden`	Verificar `tenant-org` y `plan-id` del perfil activo
`500` en `/eps_fhir/eps/patients/`	Usar `fhir pacientes` (`/eps_fhir/eps/fhir/pacientes/`)
Sin keyring disponible	El CLI cae automáticamente a archivo local con permisos `0600`
La salida no es JSON	Añadir `--json --no-input` a todos los comandos
`ConfigError: HTTPS obligatorio`	Cambiar `http://` por `https://` o usar `localhost`
`ConfigError: Falta tenant`	`tecsas3 config set tenant <slug>` o usar `--tenant`
Token guardado en texto plano	Verificar que `~/.tecsas3/` tiene permisos `0700` y `credentials` `0600`
`pipe run` falla con `No module`	`pip install tecsas3-cli` o usar `python -m tecsas3_cli`
Drift de `rich` (caracteres raros en `--help`)	`pip install 'rich>=13.7,<16'`

La columna Fix contiene la acción mínima. Si el síntoma reaparece tras aplicarla, abre un issue con la salida de tecsas3 util security-check y la versión del binario.

Auditoría de seguridad

tecsas3 util security-check audita los permisos del directorio de configuración y del archivo de credenciales sin enviar datos al backend. Es la primera verificación que debes correr en producción, en CI y tras cualquier rotación de credenciales.

tecsas3 --json --no-input util security-check

Salida típica:

{
  "base_url": "https://dev.tecsas3.com",
  "verify_tls": true,
  "redact_phi": true,
  "checks": [
    {
      "path": "/home/user/.tecsas3",
      "type": "directory",
      "mode_octal": "0o700",
      "ok": true,
      "hint": null
    },
    {
      "path": "/home/user/.tecsas3/credentials",
      "type": "file",
      "mode_octal": "0o600",
      "ok": true,
      "hint": null
    }
  ],
  "status": "PASS"
}

Un status: "WARN" significa que al menos un archivo excede los permisos esperados. Aplica la corrección de la columna Fix y vuelve a correr el comando.

Diagnóstico por categoría

Autenticación y tokens

Los 401 casi siempre se deben a tokens vencidos, perfiles que apuntan al entorno equivocado o scopes insuficientes. Flujo recomendado:

tecsas3 auth list              # ver perfiles guardados
tecsas3 auth whoami            # perfil activo + scopes
tecsas3 auth use <perfil>      # cambiar de perfil sin re-login
tecsas3 auth login             # renovar credencial

Si whoami muestra el perfil equivocado, el CLI está leyendo la variable TECSAS3_PROFILE o el argumento --profile. Limpia el entorno y vuelve a intentarlo.

Multi-tenant y autorización

Los 403 rara vez son de scopes: casi siempre el perfil activo no tiene tenant-org o plan-id asignado para el recurso solicitado. El CLI inyecta los headers X-Tenant-Slug, X-Tenant-Org-ID y X-Plan-ID en cada request; si alguno falta, el backend rechaza con 403.

tecsas3 config show            # ver tenant / tenant-org / plan-id efectivos
tecsas3 config set tenant-org <id>
tecsas3 config set plan-id <id>

FHIR y rutas legacy

La ruta /eps_fhir/eps/patients/ quedó obsoleta al pasar al recurso fhir. Si una integración antigua devuelve 500, estás pegándole al endpoint equivocado. Migra a:

tecsas3 --json --no-input fhir pacientes --limit 20

Keyring y archivos de credenciales

El CLI intenta primero keyring (nativo del sistema operativo). Si no está disponible —常见的 en contenedores CI sin dbus, en sesiones SSH sin agent o en Windows sin Windows Credential Manager —, cae a ~/.tecsas3/credentials y aplica chmod 0600 automáticamente. Si el archivo termina con permisos laxos (por ejemplo tras un cp o un tar que preservó bits), security-check lo detecta y reporta WARN.

Salida no determinista para agentes

Cualquier agente de IA necesita JSON estable. Si recibes tablas, spinners o prompts, falta la combinación canónica:

tecsas3 --json --no-input <recurso> <comando> [args]

--json cambia el serializador a JSON canónico. --no-input desactiva cualquier prompt interactivo y falla con código 2 si el comando lo hubiera requerido.

Configuración inválida

HTTPS obligatorio se dispara al construir el Settings con un base_url http:// que no es localhost. En local puedes usar http://localhost:8000; en cualquier otro caso usa https:// o un proxy TLS terminado. Falta tenant se dispara cuando el comando lo requiere y ni la variable TECSAS3_TENANT, ni el perfil, ni el argumento --tenant están presentes. Soluciones:

tecsas3 config set tenant <slug>     # persistente
TECSAS3_TENANT=<slug> tecsas3 ...    # ad-hoc
tecsas3 --tenant <slug> ...          # por invocación

Pipelines (`pipe`)

pipe run resuelve cada step en un subproceso del propio CLI. El error No module named tecsas3_cli significa que el binario tecsas3 apunta a un Python sin el paquete instalado. Dos opciones:

pip install tecsas3-cli
# o, si necesitas usar la versión del repo:
python -m tecsas3_cli pipe run pipeline.yml

Drift de `rich`

rich cambió sus caracteres Unicode de caja en versiones recientes (de ┌─┐└─┘ a ╭─╮╰─╯). La suite golden de --help está anclada a rich>=13.7,<16; actualizar más allá de 16 rompe los snapshots. Si ves caracteres raros en tecsas3 --help o en los diffs de CI:

pip install 'rich>=13.7,<16'

Y regenera los golden tests sólo si la regresión es legítima:

TECSAS3_UPDATE_GOLDEN=1 pytest tests/test_golden.py

Recolectar información para un issue

Cuando ninguna de las entradas anteriores resuelve el problema, abre un issue con la siguiente información mínima:

tecsas3 --version
tecsas3 --json --no-input util security-check
tecsas3 --json --no-input auth whoami
tecsas3 --json --no-input util ping

Adjunta la salida completa (sin tokens) y el comando exacto que reprodujo el fallo.

Empezar

Conceptos

Guías

Soporte

Troubleshooting

Troubleshooting

Tabla de síntomas → fixes

Auditoría de seguridad

Diagnóstico por categoría

Autenticación y tokens

Multi-tenant y autorización

FHIR y rutas legacy

Keyring y archivos de credenciales

Salida no determinista para agentes

Configuración inválida

Pipelines (`pipe`)

Drift de `rich`

Recolectar información para un issue

​Troubleshooting

​Tabla de síntomas → fixes

​Auditoría de seguridad

​Diagnóstico por categoría

​Autenticación y tokens

​Multi-tenant y autorización

​FHIR y rutas legacy

​Keyring y archivos de credenciales

​Salida no determinista para agentes

​Configuración inválida

​Pipelines (pipe)

​Drift de rich

​Recolectar información para un issue

Troubleshooting

Tabla de síntomas → fixes

Auditoría de seguridad

Diagnóstico por categoría

Autenticación y tokens

Multi-tenant y autorización

FHIR y rutas legacy

Keyring y archivos de credenciales

Salida no determinista para agentes

Configuración inválida

Pipelines (`pipe`)

Drift de `rich`

Recolectar información para un issue