Tutoriales Técnicos

React Hook Form: trigger() dice Required con el campo lleno

2026-11-10T09:00:00.000-05:00

Escribes la contraseña en un paso de un asistente, el input la muestra, pero al llamar a trigger() el paso no avanza y el error dice que el campo es obligatorio:

const ok = await form.trigger();   // false
form.formState.errors.password;
// { type: "invalid_type", message: "Required" }

El texto exacto depende del esquema de validación; Required es el mensaje por defecto de Zod 3 para un valor ausente. La causa más probable cuando hay varias llamadas a useForm() y una función compartida que dibuja los campos es que el campo esté conectado al formulario equivocado. Este artículo explica por qué el campo "se ve" correcto, cómo comprobarlo y cómo evitar que vuelva a pasar.

Por qué pasa

Cada llamada a useForm() crea un formulario independiente. Según la documentación de React Hook Form, el objeto control que devuelve contiene los métodos para registrar componentes, y se pasa a Controller, useController, useWatch, useFieldArray o useFormState para que compartan la misma instancia de formulario. Dicho de otro modo: el campo se registra en el formulario cuyo control le entregas.

Este es el patrón con el fallo. La función recibe form, pero el Controller usa el control de otro formulario que estaba al alcance:

function renderCampo(form: any, name: string, label: string) {
  return (
    <Controller
      name={name}
      control={otroForm.control}   // otroForm: any; debería ser form.control
      render={({ field }) => (
        <label>
          {label}
          <input {...field} value={field.value ?? ''} />
        </label>
      )}
    />
  );
}

Con esto ocurre lo siguiente:

El input lee y escribe el valor en otroForm, así que se ve lleno y reacciona al teclado.
form nunca llega a conocer el campo. Con un resolver de esquema (Zod, Yup...), form.trigger() valida los valores de form, donde la contraseña no existe, y devuelve el error del esquema.
Con reglas integradas (rules={{ required: '...' }}) el efecto es peor, porque es silencioso: en una reproducción, trigger() devolvió true con el campo vacío, ya que form no tenía ningún campo registrado que validar.

TypeScript tampoco lo detectó porque los formularios implicados estaban tipados como any. Al compilar un caso de prueba con tsc en modo estricto, el error solo apareció cuando el formulario equivocado estaba tipado y tenía una forma distinta (TS2322 al usar un nombre de campo que no existe en ese tipo). Si era any, o si compartía el mismo nombre de campo, no hubo ningún aviso.

Solución

Confirma el diagnóstico con la API pública. Con el campo escrito, mira los valores del formulario que valida:
```
console.log(form.getValues());   // {} en vez de { password: '...' }
```
Si el valor aparece en getValues() de otro formulario, el campo está conectado a ese otro.

Como ayuda temporal de depuración también puedes listar los campos registrados con Object.keys(form.control._fields). Es una propiedad interna: la documentación indica no acceder a las propiedades de control, y puede cambiar entre versiones. Úsala solo para depurar y bórrala después.
Usa siempre el control del formulario que recibes. En la función compartida, cambia otroForm.control por form.control.

Elimina la posibilidad de equivocarte. Saca el campo del componente padre y haz que reciba control como parámetro. Así no hay ningún otro formulario al alcance:

import { Controller, type Control, type FieldValues, type Path } from 'react-hook-form';

type CampoProps<T extends FieldValues> = {
  control: Control<T>;
  name: Path<T>;
  label: string;
};

export function Campo<T extends FieldValues>({ control, name, label }: CampoProps<T>) {
  return (
    <Controller
      name={name}
      control={control}
      render={({ field }) => (
        <label>
          {label}
          <input {...field} value={field.value ?? ''} />
        </label>
      )}
    />
  );
}

// Uso en el paso de la contraseña:
// <Campo control={formClave.control} name="password" label="Contraseña" />

Tipa el formulario y evita any. Si prefieres pasar el formulario completo, usa UseFormReturn<T> en lugar de any. Ayuda, pero no es suficiente por sí solo, como se vio arriba; por eso conviene el paso anterior.
Comprueba el resultado de trigger() antes de avanzar. La función devuelve una promesa con un booleano, y acepta un nombre de campo o una lista de nombres para validar solo el paso actual:
```
const avanzar = async () => {
  const valido = await formClave.trigger(['password']);
  if (valido) siguientePaso();
};
```

Cómo verificar que quedó resuelto

Escribe en el campo y comprueba dos cosas en la consola:

console.log(formClave.getValues());      // { password: '...' }
console.log(await formClave.trigger());  // true

Deja ahora el campo vacío y repite: trigger() debe devolver false y el paso no debe avanzar. Si muestras el error en pantalla, aparecerá el mensaje del esquema. Esa segunda comprobación es la que detecta la variante silenciosa con reglas integradas. Si ya tienes pruebas con Testing Library, añade una que escriba en el campo, llame a trigger() y exija true, y otra que lo deje vacío y exija false.

Variantes y errores relacionados

Mismo fallo con `register`

Si en la función compartida se usa {...otroForm.register('password')}, el campo queda registrado en el otro formulario y el síntoma es el mismo.

Otros hooks que reciben `control`

useWatch, useFieldArray y useFormState también reciben control. Si les pasas el de otro formulario, se conectan a ese formulario, normalmente sin lanzar ningún error.

FormProvider

Dentro de un FormProvider la propiedad control es opcional y los componentes toman la del contexto. Si usas un proveedor por paso, comprueba que el proveedor más cercano a cada campo es el del paso correcto.

El mensaje cambia con el esquema

Required es el texto de Zod 3 para un valor ausente. Con otra versión o librería verás otro mensaje, pero la causa es la misma: el formulario validado no contiene el campo.

Resumen

Cada useForm() es un formulario independiente, y un campo pertenece al formulario cuyo control recibe su Controller.
Un campo conectado al formulario equivocado se ve y se edita con normalidad, pero trigger() del formulario correcto no lo encuentra.
Con un resolver de esquema el síntoma es Required; con reglas integradas puede ser un true silencioso con el campo vacío.
Pasa control como parámetro a un componente de módulo en lugar de cerrar sobre otro formulario, y evita any.
Diagnostica con getValues(); las propiedades internas de control son solo para depurar.

Referencias

React: key={index} hace que una fila pise a otra

2026-11-09T15:00:00.000-05:00

Tienes un formulario con filas dinámicas (las líneas de un pedido, por ejemplo). Al elegir un producto en una fila, otra fila cambia o se queda vacía. A veces, al quitar una fila, la siguiente hereda el texto que habías escrito en la anterior. React no muestra ningún error ni aviso: el síntoma solo se ve en el estado.

// Esperado: "cafe" en la fila 1 y "te" en la fila 2
[{ productId: "cafe" }, { productId: "te" }]

// Real: la segunda selección desaparece
[{ productId: "cafe" }, { productId: "" }]

Detrás suele haber tres cosas combinadas: usar el índice del arreglo como key, handlers que capturan idx y el arreglo items del render, y actualizaciones de estado calculadas a partir de ese arreglo capturado. Este es el patrón típico con el fallo (Fila es el componente que dibuja cada fila):

function Pedido() {
  const [items, setItems] = useState([
    { productId: '', precio: null },
    { productId: '', precio: null },
  ]);

  const seleccionar = async (idx, productId) => {
    const precio = await obtenerPrecio(productId);
    setItems(items.map((it, i) => (i === idx ? { productId, precio } : it)));
  };
  const quitar = (idx) => setItems(items.filter((_, i) => i !== idx));

  return (
    <ul>
      {items.map((item, idx) => (
        <Fila
          key={idx}
          item={item}
          onSelect={(p) => seleccionar(idx, p)}
          onRemove={() => quitar(idx)}
        />
      ))}
    </ul>
  );
}

Por qué pasa

1. El índice no identifica a la fila

React usa la key para saber qué elemento es cuál entre un render y el siguiente, y conserva el estado de un componente mientras se siga renderizando en la misma posición. Con key={idx} la identidad es el hueco, no la fila. Si quitas la primera fila, la segunda pasa a ocupar el índice 0 y React reutiliza el componente de ese hueco, con todo su estado interno (texto escrito, inputs no controlados, selects propios). La documentación de React advierte que el índice como clave da errores sutiles cuando los elementos se insertan, se eliminan o se reordenan, y que las claves no deben cambiar.

2. Los cierres ven una instantánea del estado

El estado de React es una instantánea por render: un handler creado en un render ve los valores de ese render. En el código anterior, seleccionar espera una respuesta asíncrona y después ejecuta setItems(items.map(...)) con el items de cuando se creó el handler. Si entre medias el usuario eligió un producto en otra fila, esa copia vieja de la lista lo borra: gana la última promesa en resolverse. En una reproducción, la fila 0 (respuesta lenta) y la fila 1 (respuesta rápida) acabaron con la fila 1 vacía.

3. Quitar con estado capturado

quitar tiene el mismo problema. Si una consulta estaba en vuelo cuando se quitó la fila, al resolverse vuelve a escribir la lista antigua y la fila quitada reaparece (también se reproduce con una prueba).

Solución

Genera un id al crear la fila, no al renderizar.
```
const crearItem = () => ({
  id: crypto.randomUUID(),
  productId: '',
  precio: null,
});
```
La documentación de React indica que, para datos generados localmente, se use un contador incremental, crypto.randomUUID() o un paquete como uuid en el momento de crear el elemento. Lo que no se debe hacer es generar la clave durante el render (por ejemplo key={Math.random()}). Según MDN, randomUUID() solo está disponible en contextos seguros (HTTPS); si tu aplicación no lo cumple, usa un contador.

Usa ese id como clave y crea el estado inicial una sola vez.

const [items, setItems] = useState(() => [crearItem(), crearItem()]);

// ...
<Fila key={item.id} item={item} /* ... */ />

Actualiza por id con funciones de actualización. React recibe una función que calcula el siguiente estado a partir del último estado pendiente, no del que capturó tu handler:

const actualizar = (id, cambios) =>
  setItems((prev) =>
    prev.map((it) => (it.id === id ? { ...it, ...cambios } : it)),
  );
const quitar = (id) => setItems((prev) => prev.filter((it) => it.id !== id));
const agregar = () => setItems((prev) => [...prev, crearItem()]);

Estas funciones deben ser puras: calculan el resultado y nada más.

Pasa el id, no el índice, a los callbacks, también en lo asíncrono.

const seleccionar = async (id, productId) => {
  const precio = await obtenerPrecio(productId);
  actualizar(id, { productId, precio });
};

// En el JSX:
// onSelect={(p) => seleccionar(item.id, p)}
// onRemove={() => quitar(item.id)}

Si la fila se quitó mientras la consulta estaba en vuelo, ninguna fila coincide con ese id y la actualización no cambia nada, en lugar de escribir sobre otra fila.

Cómo verificar que quedó resuelto

Prueba a mano con tres filas: escribe una nota distinta en cada una y quita la primera; cada nota debe seguir con su fila. Después elige productos en dos filas seguidas con la red limitada desde las herramientas del navegador: ambas selecciones deben conservarse. Repite todo dentro de <StrictMode>, que en desarrollo ejecuta dos veces los inicializadores y las funciones de actualización para detectar impurezas.

Para dejarlo cubierto con Testing Library, suponiendo que cada Fila muestra un input con la etiqueta "Nota", que guarda su texto en un estado propio, y un botón "Quitar":

import { fireEvent, render, screen } from '@testing-library/react';

it('la nota viaja con su fila al quitar la primera', () => {
  render(<Pedido />);
  const [notaA, notaB] = screen.getAllByLabelText('Nota');
  fireEvent.change(notaA, { target: { value: 'A' } });
  fireEvent.change(notaB, { target: { value: 'B' } });

  fireEvent.click(screen.getAllByText('Quitar')[0]);

  const restante = screen.getByLabelText('Nota') as HTMLInputElement;
  expect(restante.value).toBe('B');
});

Con key={idx} esta prueba falla (la fila restante muestra A); con un id estable pasa.

Variantes y errores relacionados

`key={Math.random()}` o un uuid dentro del JSX

La clave cambia en cada render, así que React desmonta y vuelve a montar todas las filas: se pierde el foco y lo que el usuario estaba escribiendo. Genera el id al crear el elemento y guárdalo en el estado.

Cuándo el índice sí es aceptable

La documentación lo admite en un caso muy concreto: una lista cuyos elementos nunca se reordenan, como las líneas de un poema fijo. Una lista donde el usuario agrega o quita filas no es ese caso.

Filas que ya vienen de una API

Usa el id que asigna la base de datos y genera uno propio solo para las filas nuevas que aún no se guardaron.

React Hook Form con useFieldArray

La documentación de useFieldArray indica usar field.id, y no el índice, como clave de cada fila.

Cambiar la clave a propósito

Cambiar la key de un componente reinicia su estado. Es una herramienta útil (por ejemplo, para resetear un formulario), pero conviene usarla solo cuando ese reinicio es lo que buscas.

Resumen

key={idx} hace que el estado interno de una fila pertenezca a la posición, no a la fila, y se mezcle al quitar o reordenar.
Un handler que usa items capturado y escribe después de un await pisa los cambios hechos en otras filas.
Asigna un id estable al crear la fila (crypto.randomUUID() o un contador) y úsalo como key.
Actualiza con setItems((prev) => ...) y localiza la fila por id, no por índice.
Verifica quitando la primera fila y eligiendo productos en dos filas con respuesta lenta.

Referencias

shadcn/ui Table: sticky y scroll horizontal no funcionan

2026-11-09T09:00:00.000-05:00

Usas el componente Table de shadcn/ui dentro de un contenedor propio para añadir dos mejoras: un encabezado fijo (position: sticky) y una barra de desplazamiento horizontal arriba de la tabla. Ninguna funciona: la barra superior nunca aparece, aunque la tabla sea mucho más ancha que el contenedor, y el encabezado se va con el resto de las filas al desplazarte. No hay errores en la consola. La causa está en el HTML que genera el propio componente:

<div class="mi-contenedor">                                  <!-- tu contenedor -->
  <div data-slot="table-container"
       class="relative w-full overflow-x-auto">               <!-- lo agrega Table -->
    <table>...</table>
  </div>
</div>

Por qué pasa

El componente Table que shadcn/ui copia a tu proyecto no renderiza solo un <table>: lo envuelve en un div con su propio desplazamiento. En el registro actual de shadcn/ui, ese div usa relative w-full overflow-x-auto y el atributo data-slot="table-container"; en proyectos generados con versiones anteriores, la clase era overflow-auto. Revisa tu archivo components/ui/table.tsx para ver cuál tienes; los dos casos se comportan igual para este problema.

Ese div interno se convierte en el contenedor de desplazamiento, y esto rompe las dos mejoras:

El scroll horizontal superior. El contenido se desborda dentro del div interno, no dentro de tu contenedor. En la prueba, el contenedor externo medía lo mismo de ancho visible que de contenido (scrollWidth igual a clientWidth), mientras que el div interno tenía 1246 px de contenido en 478 px visibles. Si calculas el desbordamiento sobre tu contenedor, siempre concluirás que no hay nada que desplazar.
El encabezado sticky. Según MDN, un elemento con position: sticky se ancla al ancestro más cercano que tiene un mecanismo de desplazamiento. Con overflow-x: auto, el eje vertical del div interno también pasa a comportarse como auto (MDN: si un eje es visible y el otro no, el visible se comporta como auto). Pero ese div no tiene altura máxima, así que nunca se desplaza verticalmente. El encabezado queda anclado a un elemento que no se mueve, y el que se desplaza es tu contenedor externo. En la prueba, tras desplazar el externo 150 px, el encabezado quedó a 149 px por encima de su borde superior: se había ido con las filas.

Solución

Neutraliza el div interno desde tu contenedor. Con una variante arbitraria de Tailwind, apuntas al hijo directo y le quitas el desplazamiento:
```
<div className="max-h-[70vh] overflow-auto [&>div]:overflow-visible">
  <Table>...</Table>
</div>
```
Según la documentación de Tailwind, las variantes arbitrarias son cadenas con el selector entre corchetes, donde & representa al elemento actual. Con Tailwind 4 se generó .\[\&\>div\]\:overflow-visible > div { overflow: visible; }. Su especificidad (0-1-1: una clase y un tipo) es mayor que la de .overflow-x-auto o .overflow-auto (0-1-0), así que gana sin importar el orden de las reglas.

Como el archivo components/ui/table.tsx vive en tu proyecto, también puedes editarlo y quitar el div envoltorio. La variante arbitraria tiene la ventaja de no tocar el componente de la librería.
Deja un solo contenedor de desplazamiento y dale una altura máxima. El max-h-[70vh] overflow-auto del ejemplo anterior cumple las dos cosas. La altura máxima es imprescindible para el sticky: en la prueba, con un contenedor que tenía overflow-x-auto pero ninguna altura máxima, el encabezado no se quedó fijo al desplazar la página (quedó 383 px por encima del borde superior de la ventana), porque seguía anclado a ese contenedor, que nunca se desplazaba en vertical.
Aplica el sticky a las celdas del encabezado. MDN indica que hace falta un valor para top (u otra propiedad de posición), y conviene dar un fondo para que las filas no se vean a través:
```
<TableHead className="sticky top-0 bg-background">Nombre</TableHead>
```

Crea la barra de desplazamiento superior. Un componente que mide el desbordamiento del contenedor, muestra una barra espejo arriba y sincroniza ambas:

import { useEffect, useRef, useState, type ReactNode } from "react"

export function ContenedorTabla({ children }: { children: ReactNode }) {
  const superiorRef = useRef<HTMLDivElement>(null)
  const cuerpoRef = useRef<HTMLDivElement>(null)
  const [ancho, setAncho] = useState(0)
  const [desborda, setDesborda] = useState(false)

  useEffect(() => {
    const cuerpo = cuerpoRef.current
    if (!cuerpo) return

    const medir = () => {
      setAncho(cuerpo.scrollWidth)
      setDesborda(cuerpo.scrollWidth > cuerpo.clientWidth)
    }

    medir()
    const observador = new ResizeObserver(medir)
    observador.observe(cuerpo)
    const tabla = cuerpo.querySelector("table")
    if (tabla) observador.observe(tabla)
    return () => observador.disconnect()
  }, [])

  const sincronizar = (origen: HTMLDivElement | null, destino: HTMLDivElement | null) => {
    if (origen && destino && destino.scrollLeft !== origen.scrollLeft) {
      destino.scrollLeft = origen.scrollLeft
    }
  }

  return (
    <div>
      <div
        ref={superiorRef}
        hidden={!desborda}
        aria-hidden="true"
        className="overflow-x-auto overflow-y-hidden"
        onScroll={() => sincronizar(superiorRef.current, cuerpoRef.current)}
      >
        <div style={{ width: ancho, height: 1 }} />
      </div>
      <div
        ref={cuerpoRef}
        role="region"
        aria-label="Tabla de datos"
        tabIndex={0}
        className="max-h-[70vh] overflow-auto [&>div]:overflow-visible"
        onScroll={() => sincronizar(cuerpoRef.current, superiorRef.current)}
      >
        {children}
      </div>
    </div>
  )
}

La comprobación destino.scrollLeft !== origen.scrollLeft evita que las dos barras se disparen eventos entre sí. El role="region" con tabIndex={0} permite desplazar la tabla con el teclado.

Observa la tabla, no solo el contenedor. Si los datos llegan después del montaje (una petición a una API, por ejemplo), la tabla se ensancha pero el contenedor mantiene su tamaño. ResizeObserver notifica los cambios del tamaño del elemento observado, así que observar solo el contenedor no avisa. En la prueba, al añadir columnas tras el montaje, el observador del contenedor no se disparó ninguna vez y el de la tabla se disparó una vez, aunque el scrollWidth del contenedor pasó a 1108 px con solo 478 px visibles. Por eso el código anterior observa ambos elementos.

Cómo verificar que quedó resuelto

Con la tabla cargada y más ancha que su contenedor, ejecuta en la consola:

const c = document.querySelector('[aria-label="Tabla de datos"]')
c.scrollWidth > c.clientWidth                    // true: el contenedor sí ve el desbordamiento
getComputedStyle(c.firstElementChild).overflowX  // "visible": el div interno ya no desplaza
c.scrollTop = 150
document.querySelector('thead th').getBoundingClientRect().top - c.getBoundingClientRect().top
// cerca de 0: el encabezado se quedó fijo arriba del contenedor

En la prueba con el componente completo y datos que llegan 300 ms después del montaje, la barra superior estaba oculta al inicio, pasó a mostrarse con un ancho de 1246 px (igual al scrollWidth), el desplazamiento de una barra se reflejó en la otra en ambos sentidos y el encabezado quedó a 0 px del borde superior del contenedor tras desplazar 150 px.

Además, una prueba de componente con Vitest y Testing Library protege la parte que puede romperse sin que nadie lo note. Como jsdom no calcula el layout, la prueba simula las medidas y ResizeObserver, y comprueba el contrato (la clase que neutraliza el div interno y que se observe la tabla):

it("neutraliza el contenedor con scroll propio de la tabla", () => {
  render(<Ejemplo />)
  const cuerpo = screen.getByRole("region", { name: "Tabla de datos" })
  expect(cuerpo.className).toContain("[&>div]:overflow-visible")
})

it("observa la tabla y no solo el contenedor", () => {
  render(<Ejemplo />)
  const observados = observadores.flatMap((o) => o.objetivos)
  expect(observados).toContain(screen.getByRole("table"))
})

Aquí Ejemplo renderiza ContenedorTabla con una tabla pequeña, y observadores es la lista de instancias del ResizeObserver simulado, con los elementos que cada una observa. Sin la clase [&>div]:overflow-visible, la primera prueba falla con expected 'max-h-[70vh] overflow-auto' to contain '[&>div]:overflow-visible'.

Variantes y errores relacionados

La tabla se monta después del contenedor

El efecto solo observa la tabla si ya existe cuando se ejecuta. Si la renderizas de forma condicional (por ejemplo, un indicador de carga en su lugar), mantén el <Table> siempre montado y muestra el estado de carga dentro de TableBody, o vuelve a ejecutar el efecto cuando aparezca (agregando esa condición a sus dependencias).

"ResizeObserver loop completed with undelivered notifications"

Es el mensaje que MDN documenta cuando la función de un ResizeObserver cambia el tamaño de un elemento que sigue observando. Aquí la función solo actualiza la barra superior, que no se observa, así que no debería aparecer. Si te pasa en una variante del código, MDN sugiere posponer el cambio de tamaño con requestAnimationFrame o evitar cambiar el tamaño cuando el elemento ya tiene el valor buscado.

Solo quieres el encabezado fijo

Si no necesitas la barra superior, los pasos 1 a 3 son suficientes: neutralizar el div interno, usar un único contenedor con altura máxima y poner sticky top-0 con fondo en las celdas del encabezado.

El sticky sigue sin funcionar

Recorre los ancestros del encabezado y busca otro con overflow distinto de visible (en las herramientas de desarrollo, el panel de estilos calculados lo muestra). Cualquiera de ellos, además del contenedor deseado, se convierte en el ancla del sticky.

Resumen

El Table de shadcn/ui envuelve la tabla en un div con overflow-x-auto (u overflow-auto en versiones anteriores) que roba el desplazamiento a tu contenedor.
Un position: sticky se ancla al ancestro más cercano con mecanismo de desplazamiento; si ese ancestro no se desplaza, el encabezado no se queda fijo.
Neutraliza el div interno con [&>div]:overflow-visible en tu contenedor y dale a este una altura máxima con overflow-auto.
Calcula el desbordamiento sobre ese único contenedor y observa la tabla con ResizeObserver para reaccionar cuando los datos llegan tarde.
Una prueba de componente que falle sin la clase evita que alguien restaure el comportamiento anterior sin darse cuenta.

Referencias

El title de un botón disabled no aparece (shadcn/ui)

2026-11-08T15:00:00.000-05:00

Quieres explicar al usuario por qué un botón está deshabilitado, así que le pones un atributo title. Pasas el mouse por encima y el tooltip nunca aparece:

<Button disabled title="Completa los campos obligatorios">
  Guardar
</Button>

No hay ningún error en la consola. El mismo title funciona en el botón cuando está habilitado, y deja de funcionar al deshabilitarlo. Este artículo explica la causa en el componente Button de shadcn/ui (React y Tailwind) y cómo mostrar el motivo con un contenedor.

Por qué pasa

La clase base del Button de shadcn/ui incluye disabled:pointer-events-none disabled:opacity-50. Con pointer-events: none, según MDN, el elemento generalmente no es el destino de los eventos del puntero: estos lo "atraviesan" y se dirigen a lo que haya debajo. El tooltip nativo de title depende de que el puntero esté sobre el elemento que tiene el atributo; en un botón con pointer-events: none, el puntero nunca llega a él. (MDN no documenta esta relación con los tooltips; es una conclusión coherente con lo observado, no una cita.)

En una prueba con Chrome se midió el efecto de la clase:

Con disabled y pointer-events: none, el botón no recibió ningún evento mouseover.
Con el mismo botón dentro de un <span>, ese span sí recibió el mouseover al pasar el puntero sobre el botón.
Con disabled pero sin pointer-events: none, Chrome sí envió mouseover al botón deshabilitado. No se probaron otros navegadores, y el comportamiento de los controles deshabilitados puede variar entre ellos.

Además, según MDN, un botón con disabled no se puede pulsar ni enfocar. Por eso un usuario de teclado nunca llega a él con la tecla Tab y no puede ver un tooltip asociado a su foco.

Solución

Confirma que tu botón tiene la clase. Como shadcn/ui copia los componentes a tu proyecto, puedes comprobarlo en PowerShell:
```
Select-String -Path src/components/ui/button.tsx -Pattern 'pointer-events'
```
Debe aparecer disabled:pointer-events-none entre las clases base. Ajusta la ruta a la de tu proyecto.

Pon el title en un contenedor que sí reciba el puntero. Un <span> alrededor del botón:

import { Button } from "@/components/ui/button"

type Props = {
  disabled: boolean
  motivo?: string
  onGuardar: () => void
}

export function BotonGuardar({ disabled, motivo, onGuardar }: Props) {
  return (
    <span
      className="inline-block"
      tabIndex={disabled ? 0 : undefined}
      title={disabled ? motivo : undefined}
    >
      <Button disabled={disabled} onClick={onGuardar}>
        Guardar
      </Button>
    </span>
  )
}

Decisiones del ejemplo: el span se renderiza siempre, para que React no desmonte y vuelva a montar el botón cuando cambia disabled; inline-block hace que el contenedor ocupe lo mismo que el botón; y tabIndex={0} solo está presente mientras el botón está deshabilitado, para darle un punto de foco al teclado sin añadir una parada extra cuando el botón funciona.

Cubre el comportamiento con una prueba. Con Vitest y Testing Library, la prueba comprueba que el title está en el contenedor y no en el botón:

import { describe, expect, it, vi } from "vitest"
import { render, screen } from "@testing-library/react"
import { BotonGuardar } from "./BotonGuardar"

const MOTIVO = "Completa los campos obligatorios"

describe("BotonGuardar", () => {
  it("muestra el motivo en el contenedor cuando está deshabilitado", () => {
    render(<BotonGuardar disabled motivo={MOTIVO} onGuardar={vi.fn()} />)

    const contenedor = screen.getByTitle(MOTIVO)
    const boton = screen.getByRole("button", { name: "Guardar" })

    expect(contenedor.tagName).toBe("SPAN")
    expect(contenedor).toContainElement(boton)
    expect(boton).toBeDisabled()
    expect(boton).not.toHaveAttribute("title")
  })
})

getByTitle busca el elemento cuyo atributo title coincide con el texto. Si pones el title de vuelta en el botón, esta prueba falla con Expected: "SPAN" / Received: "BUTTON". Un detalle: jsdom no carga tus clases de Tailwind, así que la prueba no detecta pointer-events; verifica la estructura que lo soluciona, no el efecto visual.

Si necesitas que también funcione con teclado o en pantallas táctiles, usa un Tooltip en vez de title. La documentación de shadcn/ui para Tooltip incluye un ejemplo para botones deshabilitados con el mismo recurso, un span como hijo del disparador:
```
<Tooltip>
  <TooltipTrigger asChild>
    <span className="inline-block" tabIndex={0}>
      <Button disabled>Guardar</Button>
    </span>
  </TooltipTrigger>
  <TooltipContent>Completa los campos obligatorios</TooltipContent>
</Tooltip>
```
El tabIndex={0} es un añadido de este artículo, no parte del ejemplo oficial. La documentación de Radix indica que el Tooltip se abre al pasar el puntero o al recibir foco el disparador, y no menciona los botones deshabilitados; por eso conviene que el span pueda recibir foco.

Cómo verificar que quedó resuelto

Ejecuta la prueba (npx vitest run). Debe pasar con el contenedor y fallar si mueves el title al botón.
En el navegador, pasa el mouse sobre el botón deshabilitado y espera aproximadamente un segundo: debe aparecer el tooltip con el motivo. El tooltip nativo lo dibuja el navegador fuera del DOM, así que no se puede inspeccionar con las herramientas de desarrollo ni con las pruebas automatizadas; esta comprobación es manual.
Comprueba a qué elemento llega el puntero. Ubica las coordenadas del botón en la consola y pregunta qué elemento hay allí:
```
const b = document.querySelector('button:disabled')
const r = b.getBoundingClientRect()
document.elementFromPoint(r.x + r.width / 2, r.y + r.height / 2)
```
En la prueba devolvió el span contenedor, no el botón.
Con el teclado, pulsa Tab: el contenedor debe recibir el foco mientras el botón esté deshabilitado.

Variantes y errores relacionados

Los clics atraviesan el botón deshabilitado

Con pointer-events: none, un clic sobre el botón deshabilitado se dirige al elemento que está debajo. En la prueba, el clic llegó al span y subió hasta el manejador onClick de un contenedor superior. Si el botón está dentro de una tarjeta o fila clicable, puede dispararse esa acción. Si no lo quieres, detén la propagación en el span (onClick={(e) => e.stopPropagation()}).

Usar `aria-disabled` en lugar de `disabled`

Un botón con aria-disabled="true" sigue siendo enfocable y puede recibir el puntero, por lo que no necesita el contenedor. Pero MDN aclara que este atributo solo cambia la semántica que se comunica a las tecnologías de apoyo: tienes que suprimir tú mismo la acción (también la activación con teclado), darle el estilo de deshabilitado y no puedes apoyarte en las clases disabled: de shadcn/ui.

Las limitaciones del atributo `title`

MDN advierte que su uso es muy problemático para personas que usan pantallas táctiles, navegan con teclado o usan tecnologías de apoyo, y recomienda una técnica más accesible para los tooltips. Si el motivo es importante, considera además mostrarlo como texto visible junto al botón.

Resumen

El Button de shadcn/ui aplica disabled:pointer-events-none, y con eso el puntero nunca llega al botón deshabilitado, así que su title no se muestra.
La solución es poner el title (o el disparador del Tooltip) en un <span> que envuelva el botón.
Renderiza el span siempre y añade tabIndex={0} solo mientras el botón está deshabilitado.
Una prueba con getByTitle verifica que el título está en el contenedor; el tooltip nativo se comprueba a mano.
Para teclado y pantallas táctiles, prefiere un Tooltip al atributo title.

Referencias

Modal sin scroll en pantallas de poca altura (CSS)

2026-11-08T09:00:00.000-05:00

Abres un modal con una lista larga. En una pantalla alta se ve bien, pero en una ventana ancha y poco alta (una laptop con la ventana reducida o con las herramientas de desarrollo abiertas, por ejemplo) el contenido queda cortado: no aparece ninguna barra de desplazamiento, la rueda del mouse no hace nada y el botón final del formulario es inalcanzable. No hay ningún mensaje de error; el problema está en el CSS. Este es el patrón que lo provoca:

/* Panel.module.css: clase compartida por varias pantallas */
.panel {
  max-height: 90vh;
  overflow: hidden; /* por ejemplo, para recortar esquinas redondeadas */
}

@media (max-width: 768px) {
  .panel {
    overflow-y: auto;
  }
}

Por qué pasa

La clase compartida solo permite el desplazamiento dentro de una media query de ancho. Cuando la ventana mide más de 768 px de ancho, esa regla no se aplica y el contenedor queda con overflow: hidden. Según MDN, con ese valor el contenido que sobresale se recorta, no hay barras de desplazamiento y el usuario no puede verlo arrastrando en una pantalla táctil ni con la rueda del mouse.

El error es relacionar el ancho de la ventana con la necesidad de scroll. Lo que determina si hace falta desplazarse es la altura disponible frente a la altura del contenido, y ese cruce puede darse con cualquier ancho. Si el modal tiene position: fixed, tampoco sirve desplazar la página de fondo: el modal no se mueve con ella.

En la prueba con 8 elementos en la lista y una ventana de 1280 × 400 píxeles, el contenedor tenía un contenido de 529 px dentro de un área visible de 360 px, con overflow-y en hidden: el botón quedó fuera de la ventana y no se pudo alcanzar con la rueda ni con un clic. Con una ventana de 600 px de ancho, la misma pantalla sí funcionaba, porque ahí se aplicaba la media query. Por eso el fallo pasa desapercibido si solo se prueba en móvil o en un monitor grande.

Solución

Reproduce el problema. Abre el modal con más elementos de los que caben y reduce la altura de la ventana (por ejemplo, a unos 400 px). En la consola, comprueba si hay desbordamiento y qué valor tiene overflow-y:
```
const modal = document.querySelector('[role="dialog"]')
console.log(getComputedStyle(modal).overflowY, modal.scrollHeight, modal.clientHeight)
// hidden 529 360  -> el contenido es más alto que el área visible y está recortado
```
Los números dependerán de tu contenido; lo importante es que scrollHeight sea mayor que clientHeight con hidden.
Dale al modal su propio contenedor, con altura máxima y scroll independientes del ancho. No reutilices la clase compartida:
```
.dialogo {
  box-sizing: border-box;
  max-height: 90vh; /* respaldo para navegadores sin dvh */
  max-height: 90dvh;
  overflow-y: auto;
}
```
Con overflow-y: auto la barra solo aparece cuando el contenido supera la altura máxima. box-sizing: border-box hace que el relleno (padding) cuente dentro de esos 90 %; sin él, la altura máxima se aplica solo al contenido y el modal puede terminar más alto que la ventana.

La unidad dvh (altura de la ventana dinámica) tiene en cuenta las barras del navegador móvil que se expanden o se retraen; según web.dev, está disponible desde Chrome 108, Edge 108, Firefox 101 y Safari 15.4. La línea con vh sirve de respaldo: un navegador que no entiende dvh descarta esa declaración y conserva la anterior. En una prueba con una unidad inexistente (90foo), el navegador mantuvo el valor en vh.

Úsalo en el componente. El modal ya no depende de la clase compartida:

<div className={styles.fondo}>
  <div
    className={styles.dialogo}
    role="dialog"
    aria-modal="true"
    aria-labelledby="titulo-modal"
  >
    <h2 id="titulo-modal">Elementos</h2>
    <ul>{items.map((item) => <li key={item.id}>{item.nombre}</li>)}</ul>
    <button type="button" onClick={guardar}>Guardar</button>
  </div>
</div>

Opcional: mantén visibles el título y los botones y desplaza solo la lista. Es una variante de diseño, no un requisito:
```
.dialogo {
  box-sizing: border-box;
  display: flex;
  flex-direction: column;
  max-height: 90dvh;
}

.cabecera,
.pie {
  flex: none;
}

.cuerpo {
  overflow-y: auto;
}
```
Aquí el contenedor no desplaza nada; el scroll queda en .cuerpo, y la cabecera y el pie siempre se ven. En la prueba funcionó sin ajustes adicionales.

Cómo verificar que quedó resuelto

Reduce la ventana a unos 1280 × 400 con 8 o más elementos en la lista. Al mover la rueda del mouse sobre el modal, el contenido debe desplazarse y el botón final debe poder alcanzarse y pulsarse. En la prueba, el borde inferior del botón pasó de estar a 525 px del borde superior de la ventana (fuera de una ventana de 400 px de alto) a 356 px tras desplazar, y el clic se registró.
Repite la comprobación de la consola: getComputedStyle(modal).overflowY debe devolver auto.
Prueba una ventana alta (por ejemplo 1280 × 900): no debe aparecer barra de desplazamiento si todo cabe (scrollHeight igual a clientHeight).
Prueba una ventana estrecha (600 px de ancho): debe seguir funcionando igual.

Variantes y errores relacionados

Una media query de altura para compactar el diseño

La característica height de las media queries mide la altura de la ventana y admite min-height y max-height. Puedes usarla para reducir espacios en pantallas bajas, por ejemplo @media (max-height: 40rem), pero como complemento: el scroll del modal no debe depender de ella.

`vh`, `dvh` o `svh`

MDN indica que vh equivale a lvh (la altura con las barras del navegador retraídas), por lo que en móviles con barras visibles el modal puede quedar parcialmente fuera de la ventana. dvh se ajusta a las barras, pero MDN advierte que su tamaño no es estable y puede cambiar mientras el usuario se desplaza. svh usa la ventana más pequeña y es la opción más predecible si no quieres cambios de tamaño en pleno scroll.

El mismo fallo en otros contenedores

Busca otras clases reutilizadas cuyo overflow solo cambie dentro de una media query de ancho. Cualquier contenedor con altura máxima y overflow: hidden puede esconder contenido de la misma forma.

Resumen

Un contenedor con overflow: hidden recorta el contenido sin ofrecer barra de desplazamiento ni forma de alcanzarlo.
El scroll no debe depender de una media query de ancho: ventanas anchas pero bajas siguen necesitándolo.
Dale al modal su propio contenedor con max-height: 90dvh (con 90vh como respaldo), overflow-y: auto y box-sizing: border-box.
Si quieres cabecera y pie fijos, usa una columna flex y pon overflow-y: auto solo en el cuerpo.
Prueba con poca altura, no solo con poco ancho.

Referencias

El texto de la pestaña activa desaparece al pasar el mouse

2026-11-07T15:00:00.000-05:00

Tienes un componente de pestañas con CSS Modules. La pestaña activa se ve bien (texto claro sobre fondo de color), pero en cuanto pasas el mouse por encima, el texto desaparece y queda solo un bloque de color liso. No hay ningún error en la consola: el síntoma es puramente visual. Este es el patrón de CSS que lo causa:

/* Tabs.module.css */
.tab {
  color: var(--color-muted);
  background: transparent;
}

.tab:hover {
  color: var(--color-primary);
}

.tabActive {
  color: var(--color-on-primary);
  background: var(--color-primary);
}

En JSX, la pestaña activa recibe las dos clases, por ejemplo className={`${styles.tab} ${activa ? styles.tabActive : ''}`}. Aunque .tabActive aparece después en el archivo, al pasar el mouse el color del texto cambia al color primario, el mismo del fondo.

Por qué pasa

Cuando dos reglas de la misma hoja de estilos compiten por la misma propiedad, gana la de mayor especificidad; el orden en el archivo solo desempata cuando la especificidad es igual. MDN explica que la especificidad se compara en tres columnas (identificadores, clases y tipos), y que las clases, los atributos y las pseudoclases como :hover suman lo mismo en la columna central. En este caso:

.tab:hover es una clase más una pseudoclase: especificidad 0-2-0.
.tabActive es una sola clase: especificidad 0-1-0.

Para la propiedad color, la regla de :hover gana a la de la clase activa, aunque esta última esté más abajo. El background no tiene conflicto (solo lo define .tabActive), así que se mantiene. El resultado es texto en color primario sobre fondo en color primario. Con colores idénticos, la relación de contraste es de 1:1; el criterio 1.4.3 de WCAG pide al menos 4.5:1 para texto normal. En una prueba con colores de ejemplo, el contraste calculado de la pestaña activa con el mouse encima fue de 1,00:1.

CSS Modules no cambia esto. Solo renombra las clases a nombres únicos, y la especificidad de los selectores sigue siendo la misma.

Solución

Confirma la causa. En las herramientas de desarrollo del navegador, selecciona la pestaña activa y fuerza el estado :hover desde el panel de estilos. Verás tachada la declaración de color de .tabActive y aplicada la de .tab:hover.
Excluye la pestaña activa de la regla de hover. Es la opción más clara y no depende del orden de las reglas:
```
.tab:not(.tabActive):hover {
  color: var(--color-primary);
}
```
La regla de hover deja de coincidir con la pestaña activa, así que nada pisa su color. Procesado con postcss-modules, la clase local dentro de :not() también se renombra y el selector sigue funcionando. Según MDN, :not() toma la especificidad del selector más específico de su argumento; aquí eso solo importa para las demás pestañas.
Alternativa: subir la especificidad de la regla activa. Si prefieres no tocar la regla de hover, combina las dos clases:
```
.tab:hover {
  color: var(--color-primary);
}

.tab.tabActive {
  color: var(--color-on-primary);
  background: var(--color-primary);
}
```
Atención: .tab.tabActive vale 0-2-0, igual que .tab:hover. Con especificidad igual decide el orden, y en la prueba el problema volvió al declarar .tab.tabActive antes que .tab:hover. Si usas esta opción, mantén la regla activa después de la de hover, o añade un selector explícito que no dependa del orden:
```
.tab.tabActive:hover {
  color: var(--color-on-primary);
}
```
Busca el mismo patrón en el resto del proyecto. En PowerShell:
```
Get-ChildItem src -Recurse -Filter *.module.css | Select-String -Pattern ':hover|:focus|:active'
```
Revisa cada coincidencia: si el selector con pseudoclase apunta a una clase base y existe otra clase "de estado" (activa, seleccionada, primaria) que define la misma propiedad, tienes el mismo conflicto.

Cómo verificar que quedó resuelto

La comprobación manual consiste en pasar el mouse sobre la pestaña activa: el texto debe seguir visible. Para una comprobación más objetiva, fuerza :hover en las herramientas de desarrollo y compara los valores de color y background-color en la pestaña Computed; no deben ser iguales. El selector de color de Chrome también muestra la relación de contraste.

Si usas Playwright, puedes automatizarlo con propiedades estándar del DOM:

const activa = page.locator('[role="tab"][aria-selected="true"]')
await activa.hover()
const [color, fondo] = await activa.evaluate((el) => {
  const estilos = getComputedStyle(el)
  return [estilos.color, estilos.backgroundColor]
})
// color y fondo deben ser distintos

Comprueba también que las pestañas inactivas conservan su efecto de hover: con la opción de :not(), pasar el mouse por una pestaña inactiva debe seguir cambiando su color al primario.

Variantes y errores relacionados

El mismo conflicto con `:focus`, `:active` o `:disabled`

Cada pseudoclase simple agregada a la clase base (:hover, :focus-visible, :active) suma el equivalente a una clase de especificidad. Por eso un .boton:focus-visible o un .boton:active también puede imponerse a una clase de estado como .botonPrimario. La corrección es la misma: excluir el estado con :not() o declarar el selector combinado explícito.

Si el hover cambia también el fondo

Si la regla de hover define color y background, ambas propiedades de la pestaña activa serían reemplazadas por las del hover (la regla de hover gana en las dos). Según los colores elegidos, el texto podría seguir siendo legible, pero la pestaña activa perdería su fondo distintivo al pasar el mouse. La exclusión con :not() resuelve los dos casos.

No uses `!important` como atajo

Funciona a corto plazo, pero obliga a usar más !important en cada excepción posterior. Es preferible ajustar los selectores.

No dependas del orden entre archivos

Cuando la solución depende de que una regla se declare después de otra y ambas están en archivos distintos, el resultado puede cambiar según el orden en que el empaquetador incluya los módulos CSS. Con especificidades distintas, ese riesgo desaparece.

Resumen

Una clase con pseudoclase (.tab:hover, 0-2-0) gana a una clase sola (.tabActive, 0-1-0), sin importar el orden en el archivo.
El resultado fue texto y fondo del mismo color: contraste 1:1, muy por debajo del 4.5:1 que pide WCAG.
Solución preferida: .tab:not(.tabActive):hover.
Si subes la especificidad con .tab.tabActive, queda un empate con .tab:hover y decide el orden: declárala después.
Busca el mismo patrón en otras pseudoclases y componentes con clases de estado.

Referencias

ESLint: "is defined but never used" en componentes JSX

2026-11-07T09:00:00.000-05:00

Ejecutas ESLint en un proyecto React con Vite y configuración flat (ESLint 9), y varios componentes aparecen como no usados aunque se renderizan sin problema:

npx eslint src

src/App.jsx
  1:8   error  'MiComponente' is defined but never used  no-unused-vars
  2:10  error  'Otro' is defined but never used          no-unused-vars

En ese archivo, MiComponente se usa como <MiComponente /> y Otro como <Otro.Hijo />. La aplicación funciona; el error es un falso positivo de la regla no-unused-vars. Este artículo explica por qué ocurre y cómo corregirlo activando una sola regla de eslint-plugin-react, sin llenar el proyecto de errores nuevos.

Por qué pasa

La regla no-unused-vars del núcleo de ESLint no considera que una etiqueta JSX sea un uso de la variable. La documentación de react/jsx-uses-vars lo explica así: el no-unused-vars del núcleo no detecta las variables usadas en JSX, y esa regla del plugin existe para marcarlas como usadas. En la prueba de este artículo se comprobó el mismo efecto: con solo js.configs.recommended y el analizador por defecto, un componente importado y usado únicamente como etiqueta se reporta como no usado.

Esto solo afecta a los nombres que aparecen exclusivamente en JSX. Si el mismo identificador también se usa en código JavaScript normal (por ejemplo, se pasa a una función), la regla lo cuenta como usado y no hay error.

Por qué no lo viste antes: la plantilla de React de create-vite (versión 7.0.0, la que se revisó) incluye en su eslint.config.js esta excepción, que oculta el problema para cualquier nombre que empiece con mayúscula o guion bajo:

'no-unused-vars': ['error', { varsIgnorePattern: '^[A-Z_]' }],

Si tu configuración no tiene esa línea (por ejemplo, porque la quitaste, o porque armaste el archivo solo con js.configs.recommended y los plugins de hooks y refresh), el falso positivo aparece.

Solución

Instala el plugin de React para ESLint.

npm install --save-dev eslint-plugin-react

Regístralo y activa solo react/jsx-uses-vars. Un eslint.config.js mínimo queda así; si ya tienes un bloque para tus archivos .jsx (con react-hooks o react-refresh), agrega ahí react en plugins y la regla en rules:

import js from '@eslint/js'
import globals from 'globals'
import react from 'eslint-plugin-react'

export default [
  { ignores: ['dist'] },
  js.configs.recommended,
  {
    files: ['**/*.{js,jsx}'],
    plugins: { react },
    languageOptions: {
      ecmaVersion: 'latest',
      globals: globals.browser,
      parserOptions: {
        ecmaFeatures: { jsx: true },
        sourceType: 'module',
      },
    },
    rules: {
      'react/jsx-uses-vars': 'error',
    },
  },
]

El nombre del plugin en plugins (react) define el prefijo de las reglas (react/...). Según la documentación de la regla, react/jsx-uses-vars solo tiene efecto si no-unused-vars está activada, algo que ya hace js.configs.recommended.

Opcional: detecta imports que faltan. Como ESLint no ve las etiquetas JSX como referencias, tampoco avisa cuando usas un componente que nunca importaste (no-undef guarda silencio y el error aparece recién al ejecutar la app). Esta regla del mismo plugin lo cubre:
```
rules: {
  'react/jsx-uses-vars': 'error',
  'react/jsx-no-undef': 'error',
},
```
Evita activar el preset completo solo para esto. react.configs.flat.recommended incluye muchas más reglas. En la prueba, un componente tan simple como function Tarjeta({ titulo, contenido }) sin PropTypes generó errores react/prop-types por cada propiedad, además de un aviso de que no se había definido la versión de React. En un proyecto real con muchos componentes, eso puede sumar cientos de errores que no tienen relación con el falso positivo. Si más adelante quieres el preset, agrega también react.configs.flat['jsx-runtime'] (la documentación del plugin lo indica para React 17 o superior), define settings.react.version y decide si desactivas 'react/prop-types': 'off'.

Cómo verificar que quedó resuelto

npx eslint src

Los errores de componentes usados solo en JSX deben desaparecer. Lo que quede son problemas reales: en la prueba, el único error restante fue un componente sin importar, reportado por react/jsx-no-undef.

Para confirmar que la regla está activa en un archivo concreto, en PowerShell:

npx eslint --print-config src/App.jsx | Select-String 'jsx-uses-vars'

Para comprobar que no apagaste la detección general, deja un import sin usar en cualquier archivo, por ejemplo import { sinUsar } from './util.js'. ESLint debe seguir reportando 'sinUsar' is defined but never used.

Variantes y errores relacionados

La alternativa de la plantilla: `varsIgnorePattern`

Puedes volver al enfoque de la plantilla de Vite con 'no-unused-vars': ['error', { varsIgnorePattern: '^[A-Z_]' }]. La opción varsIgnorePattern exime de la comprobación a las variables cuyo nombre coincide con la expresión regular. Funciona, pero a costa de que ESLint deje de avisar de cualquier variable, función o importación con nombre en mayúscula que realmente no se use. Con react/jsx-uses-vars mantienes la detección completa.

Proyectos con TypeScript

Con typescript-eslint el problema no apareció en la prueba: un componente importado y usado solo como etiqueta en un archivo .tsx no se reportó, mientras que un import realmente sin usar sí. Si ves este error en un proyecto TypeScript, revisa que el analizador de typescript-eslint esté aplicado a esos archivos.

¿Y `react/jsx-uses-react`?

Sirve para el caso en que importas React solo para que la transformación JSX clásica lo use. Con la transformación automática de JSX (React 17 o superior), no necesitas importar React en cada archivo: los archivos de la plantilla de React de create-vite que se revisó (main.jsx y App.jsx) no lo importan. El README del plugin indica que la configuración jsx-runtime desactiva esta regla.

La regla no tiene efecto

Revisa tres cosas: que el plugin esté registrado en plugins con el mismo nombre que usas en el prefijo de la regla, que el bloque tenga un files que incluya tus archivos .jsx, y que no-unused-vars esté realmente activada para esos archivos.

Resumen

El no-unused-vars del núcleo de ESLint no cuenta las etiquetas JSX como uso, así que marca componentes que sí renderizas.
La plantilla de Vite lo oculta con varsIgnorePattern: '^[A-Z_]'; sin esa línea, el falso positivo aparece.
Instala eslint-plugin-react y activa solo 'react/jsx-uses-vars': 'error'.
No actives el preset completo solo para esto: añade errores como react/prop-types que no tienen relación.
Añade react/jsx-no-undef si quieres que ESLint detecte componentes sin importar.

Referencias

ssh: Could not resolve hostname con un alias de config

2026-11-06T15:00:00.000-05:00

Escribes el alias que definiste en ~/.ssh/config para abrir un túnel hacia una base de datos y ssh responde que no lo conoce:

PS> ssh -N -L 5436:localhost:5432 mi_alias_db
ssh: Could not resolve hostname mi_alias_db: Host desconocido.

El texto después de los dos puntos depende del sistema y del idioma (en Windows con idioma inglés suele ser No such host is known.; en Linux, Name or service not known). El escenario es OpenSSH en Windows 11, un archivo config con un servidor intermedio (bastión) mediante ProxyJump y una base de datos PostgreSQL detrás de él, a la que luego te conectas desde DataGrip. Las comprobaciones de este artículo se hicieron con OpenSSH for Windows 9.5 y con OpenSSH 10.3, el que incluye Git para Windows.

Por qué pasa

ssh busca en el archivo de configuración un bloque Host que coincida con el nombre que escribiste. Si ninguno coincide, no falla por eso: trata el nombre como un servidor real, porque la documentación de HostName dice que su valor por defecto es el nombre dado en la línea de comandos. Entonces intenta resolver mi_alias_db por DNS y falla. Por eso este error significa casi siempre que el alias no existe en el archivo que ssh está leyendo.

En este caso, el bloque nuevo del servidor de base de datos se copió de uno existente y conservó el mismo nombre en Host, así que el alias mi_alias_db nunca llegó a definirse:

Host bastion
    HostName bastion.example.com
    User deploy

Host mi_alias_app
    HostName app.example.com
    User deploy
    ProxyJump bastion

# Bloque nuevo copiado del anterior: faltó cambiar el nombre
Host mi_alias_app
    HostName db.example.com
    User postgres
    ProxyJump bastion
    ServerAliveInterval 30

Además, el bloque duplicado no es "config muerta" del todo. El manual de ssh_config establece que, salvo indicación contraria, para cada directiva se usa el primer valor especificado. Los dos bloques con el mismo Host se combinan: lo que el primero ya definió (HostName, User) gana, y el segundo solo aporta lo que al primero le falta (aquí, ServerAliveInterval). Es una mezcla fácil de pasar por alto.

Solución

Mira cómo resuelve ssh el alias, sin conectarse. La opción -G imprime la configuración resultante tras evaluar los bloques Host y Match, y termina:
```
:: cmd
ssh -G mi_alias_db | findstr /b /i "hostname proxyjump"

# PowerShell
ssh -G mi_alias_db | Select-String '^(hostname|proxyjump|user) '

# Git Bash o Linux
ssh -G mi_alias_db | grep -E '^(hostname|proxyjump|user) '
```
Usa /b en findstr: sin él, la búsqueda de hostname también devuelve líneas como canonicalizehostname false. Ojo con una trampa: con un alias inexistente, ssh -G no da error (termina con código 0). Si la línea hostname repite el alias en lugar de un servidor real, es que ningún bloque coincidió.
Localiza los bloques duplicados. El modo detallado indica qué archivo se lee y qué líneas se aplican:
```
ssh -v -G mi_alias_app 2>&1 | Select-String 'Reading configuration|Applying options'
```
Debes ver una línea "Applying options for" por cada bloque que coincide. Con el archivo de arriba aparece dos veces (líneas 5 y 11). Con un alias inexistente no aparece ninguna. También puedes listar todas las líneas Host con su número:
```
Select-String -Path "$env:USERPROFILE\.ssh\config" -Pattern '^\s*Host\s'
```
Haz una copia y renombra el bloque. Guarda el archivo antes de tocarlo y cambia el segundo Host por el alias que querías:
```
Copy-Item "$env:USERPROFILE\.ssh\config" "$env:USERPROFILE\.ssh\config.bak"
```
```
Host mi_alias_db
    HostName db.example.com
    User postgres
    ProxyJump bastion
    ServerAliveInterval 30
```
Si usas un bloque general Host *, déjalo al final: el manual recomienda poner las declaraciones más específicas al principio del archivo y los valores generales al final.
Vuelve a comprobar con -G. Ahora hostname debe ser db.example.com, user debe ser postgres y proxyjump debe ser bastion.
Abre el túnel en su propia consola.
```
ssh -N -L 5436:localhost:5432 mi_alias_db
```
-N evita ejecutar un comando remoto (sirve solo para reenviar puertos). -L 5436:localhost:5432 reenvía el puerto local 5436 al puerto 5432 de localhost, un nombre que se resuelve desde el servidor al que ssh se conecta, es decir, el de la base de datos. La consola se queda sin mensajes y sin devolver el control: es lo normal; no la cierres mientras uses el túnel. Si el puerto 5436 ya está ocupado, elige otro y úsalo también en el cliente.

Si el túnel se cae tras un rato inactivo, añade -o ServerAliveInterval=30 al comando o la línea ServerAliveInterval 30 al bloque. El manual explica que, si no llegan datos del servidor en ese intervalo, ssh envía un mensaje para pedir respuesta; el valor por defecto es 0, que no envía nada.
Conecta DataGrip al extremo local del túnel. Crea un origen de datos de tipo PostgreSQL con Host localhost, Port 5436 y tu usuario, contraseña y base de datos. Deja desactivada la opción "Use SSH tunnel" de la pestaña SSH/SSL. La documentación de DataGrip describe los tipos de autenticación del túnel integrado (contraseña, par de claves y "OpenSSH config and authentication agent"), pero no menciona ProxyJump. El soporte de saltos intermedios en el cliente SSH integrado de cada herramienta puede variar, y abrir el túnel con el ssh del sistema evita depender de eso.

Cómo verificar que quedó resuelto

ssh -G mi_alias_db muestra el hostname, el user y el proxyjump esperados, y ssh -v -G mi_alias_db muestra una sola línea "Applying options for".
Con el túnel abierto, en otra consola: Get-NetTCPConnection -LocalPort 5436 -State Listen debe devolver una fila.
En DataGrip, "Test Connection" termina bien. Si tienes psql, puedes probar también desde la terminal:

psql "host=localhost port=5436 dbname=mi_base user=mi_usuario" -c "select 1"

Variantes y errores relacionados

El error nombra un servidor real y no el alias

Si el mensaje dice Could not resolve hostname db.example.com (el valor de tu HostName), el alias sí existe y el problema es otro: un HostName mal escrito, un DNS interno que no resuelve o un bastión inaccesible. Distinguir entre "nombre del alias" y "nombre del servidor" en el mensaje te ahorra buscar en el lugar equivocado.

ssh no lee el archivo que crees

OpenSSH lee config, sin extensión, dentro de la carpeta .ssh de tu usuario. En Windows es fácil que un editor lo guarde como config.txt. La línea "Reading configuration data" de ssh -v -G muestra exactamente qué archivo se leyó. La opción -F permite probar otro archivo de configuración sin tocar el de uso diario.

Un `Host *` al principio del archivo

Como se usa el primer valor de cada directiva, un bloque general colocado arriba pisa los valores específicos de los bloques siguientes. Ponlo siempre al final.

Probar el salto sin editar el archivo

La opción -J de ssh permite indicar el servidor intermedio en la línea de comandos. Es útil para descartar si el fallo está en el archivo config o en el acceso al bastión (consulta el manual de ssh para la sintaxis).

Resumen

"Could not resolve hostname" con un alias significa que ningún bloque Host coincidió y ssh trató el alias como un nombre DNS.
Un Host repetido por copiar y pegar un bloque deja sin definir el alias nuevo; además, ssh usa el primer valor de cada directiva y combina los bloques duplicados.
Diagnostica con ssh -G alias (el hostname no debe repetir el alias) y ssh -v -G alias para ver qué bloques se aplican.
Renombra el bloque correcto, abre el túnel con ssh -N -L 5436:localhost:5432 alias en su propia consola y añade ServerAliveInterval 30 contra cortes por inactividad.
En DataGrip, usa una conexión PostgreSQL normal a localhost:5436 en lugar de su pestaña SSH si el cliente integrado no respeta ProxyJump.

Referencias

Git: Permission denied por falta del bit de ejecución

2026-11-06T09:00:00.000-05:00

Subes unos scripts desde Windows, el servidor Ubuntu los descarga con git pull y ninguno se puede ejecutar:

$ ls -l tools/
-rw-r--r-- 1 deploy deploy  412 oct 11 10:00 build.py
$ ./tools/build.py
bash: ./tools/build.py: Permission denied

Si los lanza systemd u otro agente, el servicio falla al arrancar el proceso (en el estado de systemd suele verse status=203/EXEC). Lo habitual es arreglarlo en el servidor con chmod +x, y entonces aparece el segundo problema: en el siguiente despliegue, git pull se aborta.

error: Your local changes to the following files would be overwritten by merge:
	tools/build.py
Please commit your changes or stash them before you merge.
Aborting

Este artículo explica por qué los archivos llegan sin permiso de ejecución, cómo corregirlo en el repositorio (para que no dependa de nadie en el servidor) y cómo salir del bloqueo del git pull.

Por qué pasa

Git solo guarda un bit de permisos. La documentación de git fast-import lista los únicos modos que admite: 100644 (archivo normal, no ejecutable), 100755 (archivo ejecutable), 120000 (enlace simbólico) y 160000 (gitlink). Para un script, la diferencia entre funcionar o no en Linux es el modo 100644 frente a 100755.
En Windows el bit no se puede leer del sistema de archivos. Al ejecutar git init o git clone, Git comprueba si el sistema de archivos maneja bien el bit ejecutable y fija core.fileMode en consecuencia (esto lo describe la documentación de git config). En un repositorio nuevo creado en Windows se observa core.fileMode = false. Con ese valor, Git ignora el bit ejecutable y git add registra los archivos nuevos como 100644, incluso si empiezan con una línea #!.
En Linux el valor por defecto es true. El git pull del servidor crea los scripts con el modo registrado (100644), es decir, sin permiso de ejecución.
Por eso se aborta el git pull después de un chmod manual. Con core.fileMode = true, un cambio de modo cuenta como modificación local. Si el siguiente commit toca esos mismos archivos (por ejemplo, el commit que corrige el modo), Git se niega a sobrescribirlos.

Solución

Confirma el modo registrado. Desde Windows o desde cualquier equipo con el repositorio:
```
git ls-files -s tools/
git ls-tree HEAD tools/
```
La primera columna es el modo. Si ves 100644 en los scripts, esa es la causa.
Marca los scripts como ejecutables en el índice. En Git Bash, Linux o macOS, el shell expande el comodín:
```
git update-index --chmod=+x tools/*.py
```
En PowerShell el comodín no se expande, y git update-index lo trata como un nombre literal y falla con fatal: git update-index: cannot chmod +x 'tools/*.py'. Deja que Git resuelva el patrón:
```
git ls-files "tools/*.py" | ForEach-Object { git update-index --chmod=+x $_ }
```
Para un archivo que todavía no está en el repositorio, usa git add --chmod=+x tools/nuevo.py. Según la documentación, la opción solo cambia el bit en el índice y deja intactos los archivos en disco; por eso funciona aunque estés en Windows.
Revisa el cambio, haz commit y sube.
```
git diff --cached --summary
git commit -m "fix: marcar scripts como ejecutables"
git push
```
El resumen debe listar una línea mode change 100644 => 100755 por cada script y ninguna modificación de contenido.
Despliega y comprueba en el servidor. Tras el git pull, ls -l tools/ debe mostrar -rwxr-xr-x en los scripts.
Si el servidor tiene cambios de modo locales y el pull se aborta, primero confirma que son solo de modo:
```
git diff --summary
git diff --stat
```
El primer comando muestra líneas mode change; el segundo indica 0 inserciones y 0 eliminaciones si no cambió ninguna línea de contenido. Con eso confirmado, tienes dos salidas:
- Ignorar el modo solo en ese pull (no descarta nada): git -c core.fileMode=false pull. En una prueba con un repositorio desechable, este comando completó el pull que antes se abortaba. Si los modos del servidor coinciden con los que ahora registra el repositorio, git status debe quedar limpio.
- Restaurar los archivos: git checkout -- .. Esto descarta todos los cambios locales, también los de contenido, así que úsalo solo si git diff --stat no mostró ninguna línea cambiada.
Opcional: una red de seguridad en el script de despliegue.
```
git pull --ff-only
chmod +x tools/*.py
```
Mientras el repositorio tenga el modo 100755, ese chmod no cambia nada. Pero si alguien añade un script nuevo como 100644 y el despliegue lo hace ejecutable, el servidor acumula otra vez cambios de modo locales y puede repetirse el bloqueo del pull. Trátalo como un parche temporal y corrige siempre el modo en el repositorio.

Cómo verificar que quedó resuelto

git ls-files -s tools/
git ls-tree HEAD tools/

Ambos deben mostrar 100755. En el servidor, después del pull, ls -l debe mostrar el bit x y git status debe estar limpio. Una prueba de humo que comprueba que cada herramienta existe, es ejecutable y arranca (ajusta la opción a lo que acepten tus scripts):

for f in tools/*.py; do
  [ -x "$f" ] || { echo "No ejecutable: $f"; exit 1; }
  "$f" --help > /dev/null || { echo "Falla: $f"; exit 1; }
done
echo "OK"

Para que no vuelva a ocurrir, puedes añadir esta comprobación a tu integración continua. Falla si algún script del repositorio no está registrado como ejecutable:

if git ls-files -s -- 'tools/*.py' | grep -v '^100755'; then
  echo "Hay scripts sin bit de ejecución"; exit 1
fi

Variantes y errores relacionados

Quitar el bit ejecutable

La opción simétrica es git update-index --chmod=-x archivo.

El script tiene finales de línea CRLF

Es otro problema con síntomas distintos: el error no será Permission denied sino un fallo con el intérprete indicado en la línea #!. Para que los scripts mantengan siempre finales de línea LF, usa .gitattributes con una regla como *.sh text eol=lf; la documentación de gitattributes indica que eol=lf deja en el directorio de trabajo los mismos finales de línea que hay en el índice.

No silencies el problema con `core.fileMode = false` en el servidor

La documentación lo prevé para sistemas de archivos donde el bit ejecutable no es fiable. En un servidor Linux, desactivarlo oculta cambios de modo reales y no arregla el modo registrado en el repositorio. Para comprobar el valor y de dónde viene, usa git config --show-origin core.fileMode.

Ejecutar con el intérprete

Si no puedes cambiar el repositorio, python3 tools/build.py o bash deploy.sh funcionan sin el bit ejecutable, porque lo que se ejecuta es el intérprete. Solo es un rodeo: las unidades de systemd o los agentes que lanzan el archivo directamente seguirán fallando.

Resumen

Git registra solo dos modos para archivos normales: 100644 y 100755; desde Windows los scripts nuevos entran como 100644 porque core.fileMode suele ser false.
Corrige el modo en el repositorio: git update-index --chmod=+x (o git add --chmod=+x para archivos nuevos), commit y push.
En PowerShell el comodín no se expande: pasa los nombres con git ls-files y ForEach-Object.
Si un chmod manual bloquea el git pull, comprueba con git diff --summary que solo hay cambios de modo y usa git -c core.fileMode=false pull.
Verifica con git ls-files -s (modo 100755) y con una prueba de humo en el servidor.

Referencias

rclone Google Drive sin navegador y client_id propio

2026-11-05T15:00:00.000-05:00

Configuras un remote de Google Drive con rclone en un servidor Linux o en un contenedor y el asistente te pide abrir un navegador que ahí no existe. Si ya tenías el remote funcionando, quizá lo que ves es este aviso al ejecutar cualquier comando:

NOTICE: gdrive: This remote uses rclone's shared Google Drive client_id, which is being retired and will stop working during 2026. Create your own client_id to avoid interruption: https://rclone.org/drive/#making-your-own-client-id

También pueden aparecer errores de límite de tasa (rateLimitExceeded) al copiar muchos archivos y tokens que dejan de funcionar a los siete días. Aquí autorizamos rclone desde otro equipo con navegador y creamos un client_id propio, que resuelve el aviso, los límites y la caducidad.

Por qué pasa

OAuth necesita un navegador. La autorización de Drive se completa iniciando sesión en una página de Google. En un servidor sin navegador, la documentación de rclone propone ejecutar rclone authorize en una máquina que sí lo tenga y pegar el resultado en el servidor.
El client_id compartido se está retirando. Si dejas el campo vacío, rclone usa un client_id común a todos sus usuarios. La documentación de rclone indica que se retirará y dejará de funcionar durante 2026, y recomienda crear uno propio. El propio asistente avisa de que ese valor interno tiene bajo rendimiento: Google aplica un límite de consultas por segundo a cada client_id, y el compartido lo usan muchas personas a la vez.
Los errores de límite de tasa. La documentación de la API de Drive describe rateLimitExceeded (códigos 403 y 429) y recomienda reintentar con retroceso exponencial. En tu salida el motivo puede aparecer con otro formato (por ejemplo, en mayúsculas); lo importante es que sea un 403 o 429 de límite de tasa.
Los tokens de siete días. Si creas tu propio client_id pero dejas la pantalla de consentimiento de OAuth en estado "Testing", la documentación de OAuth de Google indica que el refresh token que se emite vence en 7 días.

Solución

Parte 1: autorizar un servidor sin navegador

Crea el remote en el servidor. Ejecuta rclone config, elige n (New remote), ponle un nombre (por ejemplo gdrive) y escribe drive como tipo. Si ya creaste tu propio client_id (parte 2), indícalo con su client_secret; si no, déjalos vacíos. Elige el alcance 1 (acceso completo), responde n a la configuración avanzada y n cuando pregunte si quieres autenticar con un navegador (Use web browser to automatically authenticate rclone with remote?; en versiones anteriores, Use auto config?).
Copia el comando que te muestra rclone. El asistente imprime algo como esto y se queda esperando en config_token>:
```
Execute the following on the machine with the web browser (same rclone
version recommended):
	rclone authorize "drive" "eyJ...(texto generado por rclone)..."
Then paste the result.
```
Copia tal cual el comando de tu versión. En versiones anteriores era simplemente rclone authorize "drive".
Ejecútalo en un equipo con navegador y rclone (la documentación recomienda la misma versión en ambos). Se abre el navegador, inicias sesión y aceptas el acceso. La terminal imprime el resultado entre las marcas Paste the following into your remote machine ---> y <---End paste. Es un JSON con tu token.
Pégalo en el servidor en el prompt config_token> y confirma con y cuando rclone muestre la configuración. Si pregunta por una unidad compartida (Shared Drive), responde que no, salvo que la uses. Después comprueba:
```
rclone lsd gdrive:
```
Debe listar las carpetas de la raíz de tu Drive.

Trata ese JSON como una contraseña. No lo pegues en chats, tickets ni registros: da acceso a tu Drive hasta que se revoque. Si se filtra, revoca el acceso de rclone desde la configuración de seguridad de tu cuenta de Google (la ubicación exacta del menú cambia con el tiempo) y vuelve a autorizar.

Alternativa en bash: leer el token sin mostrarlo en pantalla y añadir el remote al final del archivo que indica rclone config file:

read -r -s -p "Token JSON: " TOKEN; echo
umask 077
CONF="$(rclone config file | tail -n 1)"
mkdir -p "$(dirname "$CONF")"
printf '[gdrive]\ntype = drive\nscope = drive\ntoken = %s\n' "$TOKEN" >> "$CONF"
unset TOKEN

Parte 2: crear tu propio client_id

Proyecto y API. En la consola de Google Cloud, crea o elige un proyecto y habilita la API de Google Drive.
Pantalla de consentimiento. Configura el nombre de la aplicación, un correo de soporte y la audiencia. Con Google Workspace, "Internal" limita el uso a los usuarios de tu organización; con una cuenta personal normalmente eliges "External". En ese caso, si la dejas en "Testing", los tokens caducan a los 7 días (con un máximo de 100 usuarios de prueba), así que publícala ("In production") en el apartado de audiencia. Si el botón aparece deshabilitado, rclone indica añadir en Branding una página de inicio, una política de privacidad y un dominio autorizado. Para uso personal, normalmente no necesitas pasar la verificación de Google. Con "Internal", comprueba que el estado no sea "Testing": la regla de los 7 días está definida para ese estado.
Alcances. En Data Access, agrega los que lista la documentación de rclone: docs, drive y drive.metadata.readonly.
Cliente OAuth. En Credentials, crea un ID de cliente OAuth de tipo "Desktop app" y guarda el ID y el secreto.
Usa el nuevo cliente en rclone. En el servidor ejecuta rclone config, edita el remote (e) y escribe tu client_id y client_secret. Cuando pregunte si quieres renovar o reemplazar el token existente, responde que sí y, cuando pregunte por la autenticación con navegador, responde n. Si no reemplazas el token, el remote seguiría usando el emitido para el cliente anterior.
Autoriza desde el equipo con navegador con el comando que imprime el asistente o con la forma documentada en la ayuda de rclone authorize:
```
rclone authorize "drive" "<CLIENT_ID>" "<CLIENT_SECRET>"
```
Al probarlo con un client_id propio, el asistente de rclone 1.74 imprimió un comando con un bloque en base64 que contiene el client_id, el client_secret y el alcance. Base64 no es cifrado: trata también ese comando como un secreto. Pega el JSON resultante en el servidor, como en la parte 1.

Si generas el archivo rclone.conf desde Python, desactiva la interpolación de ConfigParser. Con la configuración por defecto, un signo % dentro de un valor (por ejemplo, en un token o un secreto) provoca errores:

import configparser
from pathlib import Path

ruta = Path("/ruta/a/rclone.conf")   # la que muestra: rclone config file
cfg = configparser.ConfigParser(interpolation=None)
cfg.read(ruta)
token_json = "..."   # el JSON que devolvió rclone authorize
cfg["gdrive"] = {"type": "drive", "scope": "drive", "token": token_json}
with ruta.open("w") as f:
    cfg.write(f)

Sin interpolation=None, un valor como abc%def lanza InterpolationSyntaxError al leerlo y ValueError al escribirlo. ConfigParser tampoco conserva los comentarios del archivo al reescribirlo: haz una copia antes.

Cómo verificar que quedó resuelto

rclone lsd gdrive:
rclone config show gdrive | grep '^client_id'

El aviso shared Google Drive client_id ya no aparece, y el listado funciona en cada remote que hayas migrado.
La línea client_id no está vacía. Ojo: rclone config show imprime también el token; filtra la salida como arriba y no compartas la terminal.
Pasados 7 días, el remote sigue autenticando: la aplicación no quedó en "Testing".

Como referencia de rendimiento, en una medición puntual descargando unos 600 archivos, el tiempo pasó de unos 6 minutos con el client_id compartido a unos 81 segundos con uno propio. Es un único caso; el resultado depende de la red, del tamaño de los archivos y de las cuotas de tu cuenta.

Variantes y errores relacionados

Sigue apareciendo `rateLimitExceeded` con tu propio client_id

Un client_id propio da un límite propio, pero el límite sigue existiendo. La documentación de rclone menciona una cuota por defecto de unas 10 transacciones por segundo y recomienda no superarla. Puedes reducir la presión con la opción global --tpslimit y bajar el número de transferencias en paralelo. Si el error es "User rate limit exceeded", la documentación sugiere esperar al menos 24 horas antes de reintentar.

El token deja de funcionar a la semana

Revisa el estado de publicación de la pantalla de consentimiento (debe ser "In production") y repite la autorización. El mensaje de rclone suele mencionar invalid_grant. Google lista además otras causas de un refresh token inválido: que el usuario revoque el acceso o que el token lleve seis meses sin usarse.

Alternativas a pegar el token

La documentación de rclone describe otras dos vías: copiar el archivo de configuración desde el equipo con navegador (rclone config file indica su ubicación) o reenviar el puerto 53682 por SSH entre ambos equipos para completar la autorización con el navegador de tu equipo. Las cuentas de servicio (service_account_file) son otra opción para Workspace, con requisitos propios que no se cubren aquí.

Recuerda que las preguntas del asistente y el comando de rclone authorize varían según la versión: si algo no coincide con este artículo, sigue el comando que muestra tu propio rclone.

Resumen

En un servidor sin navegador, responde que no a la autenticación con navegador, ejecuta el rclone authorize que te muestra el asistente en un equipo con navegador y pega el JSON en config_token>.
Ese JSON es un secreto: no lo compartas y revoca el acceso si se filtra.
El client_id compartido de rclone se está retirando durante 2026; crea el tuyo (proyecto, API de Drive, pantalla de consentimiento y cliente "Desktop app").
Una app External en "Testing" emite tokens que caducan a los 7 días: publícala o usa "Internal" si tienes Workspace.
Si escribes rclone.conf con Python, usa ConfigParser(interpolation=None) para que el % no rompa los valores.

Referencias

Cloudflare: redirigir www al dominio raíz (301)

2026-11-05T09:00:00.000-05:00

Tu sitio responde en example.com, pero al escribir www.example.com el navegador no encuentra nada:

$ curl -I https://www.example.com/
curl: (6) Could not resolve host: www.example.com

En el navegador verás un error de DNS, por ejemplo DNS_PROBE_FINISHED_NXDOMAIN en Chrome. Lo que quieres es que www redirija con un 301 al dominio raíz, que todo vaya por HTTPS y, de paso, tener una dirección como info en tu dominio sin montar un servidor de correo. Este artículo lo resuelve con Cloudflare. El ejemplo supone un sitio servido con Workers o Pages y un dominio .app, pero el procedimiento aplica a cualquier dominio cuyo DNS esté en Cloudflare.

Por qué pasa

No existe un registro DNS para www. Si el nombre no resuelve, la petición nunca llega a Cloudflare y ninguna regla puede actuar sobre ella.
Las reglas de redirección solo actúan sobre nombres con proxy. La documentación de Cloudflare indica que tanto Single Redirects como Bulk Redirects requieren que los registros DNS del dominio pasen por el proxy (la nube naranja). Un registro "solo DNS" (nube gris) resuelve directamente a tu servidor y Cloudflare no ve la petición.
Un nombre que solo redirige no necesita servidor. Cloudflare propone crear un registro con proxy que apunte a una dirección marcador, que no enruta tráfico a ningún origen. Para IPv6 la documentación indica la dirección 100::. El proxy recibe la petición y aplica la redirección.
En un dominio .app el HTTPS es obligatorio. Google Registry indica que .app está en la lista de precarga de HSTS, de modo que los navegadores compatibles solo se conectan por HTTPS. Los certificados de Universal SSL de Cloudflare cubren el dominio raíz y los subdominios de primer nivel, y se emiten para los registros con proxy, así que www queda cubierto.

Solución

Crea el registro DNS de www. En el panel de Cloudflare, abre DNS > Records > Add record y completa:
```
Type:   AAAA
Name:   www
IPv6:   100::
Proxy:  Proxied (nube naranja)
```
Guarda el registro. La documentación de Cloudflare ofrece también una dirección equivalente para registros A, por si prefieres IPv4; búscala en la página enlazada en las referencias.
Crea la regla de redirección. Ve a Rules > Redirect Rules (la ruta exacta del menú puede variar) y usa la plantilla "Redirect from WWW to root", o crea la regla a mano con los valores que muestra la documentación:
```
When incoming requests match (wildcard pattern)
  Request URL:  https://www.*

Then
  Target URL:             https://${1}
  Status code:            301
  Preserve query string:  activado
```
Con esta regla, https://www.example.com/blog/?a=1 redirige a https://example.com/blog/?a=1. La propia documentación aclara que las peticiones por HTTP y las que no empiezan por www no se modifican con esa regla, por eso necesitas el paso siguiente.
Fuerza HTTPS en el borde. Ve a SSL/TLS > Edge Certificates y activa "Always Use HTTPS". La opción no aparece si el modo de cifrado es "Off". Con ambas piezas, http://www.example.com/ pasa primero a HTTPS y después al dominio raíz, es decir, puede haber dos saltos.
Evita el bucle ERR_TOO_MANY_REDIRECTS. Cloudflare recomienda no hacer redirecciones en el servidor de origen. Si el modo SSL/TLS es "Flexible", Cloudflare habla con tu origen por HTTP, y si el origen redirige todo a HTTPS, ambos se devuelven la petición sin fin. La solución es quitar esa redirección del origen o cambiar el modo a "Full" o "Full (strict)" (esto exige un certificado en el origen). Si tu aplicación en Workers o Pages también redirige desde su código, deja cada redirección en un solo lugar.
Activa Email Routing para recibir correo en tu dominio. En el panel de Cloudflare abre Email Routing (la ubicación en el menú ha cambiado con el tiempo) y selecciona tu dominio. Cloudflare te muestra los registros DNS que va a añadir en el dominio raíz y los crea al completar la configuración:
- tres registros MX que apuntan a servidores de enrutamiento de Cloudflare (route1, route2 y route3 bajo mx.cloudflare.net);
- un registro TXT de SPF, cuyo valor en la documentación es v=spf1 include:_spf.mx.cloudflare.net ~all;
- un registro TXT de DKIM.
Si el dominio ya tenía registros MX, la documentación indica que Email Routing requiere los MX de Cloudflare, así que debes quitar o actualizar los existentes (y no se puede usar a la vez con servidores de correo externos). Si ya tenías un SPF, fusiónalo en un solo registro en lugar de crear un segundo.
Añade y verifica la dirección de destino. En Destination Addresses, escribe la bandeja real donde quieres recibir el correo y abre el mensaje de verificación que te envía Cloudflare para confirmarla. Las reglas permanecen desactivadas hasta que el destino esté verificado.
Crea la regla de enrutamiento. En Routing Rules, selecciona "Create routing rule", escribe info en Email pattern, selecciona tu dominio, define la acción "Send to an email" y el destino verificado. Guarda.

Email Routing sirve para recibir y reenviar correo entrante. Según la documentación, el envío saliente es otra función aparte; para responder desde la dirección info necesitas otro servicio.

Cómo verificar que quedó resuelto

Comprueba la redirección de www sin que influya la caché del navegador:

curl -sI "https://www.example.com/blog/?a=1"

La respuesta debe empezar por HTTP/2 301 (o HTTP/1.1 301, según el cliente) e incluir una cabecera location con https://example.com/blog/?a=1. Para seguir toda la cadena desde HTTP y contar los saltos:

curl -sIL -o /dev/null -w "%{http_code} %{url_effective} %{num_redirects}\n" "http://www.example.com/blog/?a=1"

El resultado final debe ser 200 con la URL del dominio raíz. Con la regla de la plantilla es esperable ver dos saltos. En Windows PowerShell usa curl.exe en lugar de curl.

Para el correo, comprueba que los registros existen:

nslookup -type=MX example.com
nslookup -type=TXT example.com

En PowerShell también sirve Resolve-DnsName example.com -Type MX. Debes ver los tres MX de Cloudflare y un TXT con include:_spf.mx.cloudflare.net. Por último, envía un mensaje a la dirección info de tu dominio desde una cuenta distinta de la de destino (algunos proveedores descartan correo que parece venir de la misma cuenta) y revisa también la carpeta de spam.

Variantes y errores relacionados

La redirección no se ejecuta

Revisa que el registro de www exista y tenga la nube naranja. Si está en "solo DNS", la petición va directa al origen y la regla se omite. Revisa también que la regla coincida: la de la plantilla solo acepta URL que empiezan por https://www..

Sigue saliendo `DNS_PROBE_FINISHED_NXDOMAIN` justo después de crear el registro

Las respuestas negativas de DNS pueden permanecer en caché durante un tiempo. Espera unos minutos, prueba con otro resolvedor o desde otra red antes de tocar la configuración.

El navegador sigue redirigiendo tras cambiar la regla

Los navegadores pueden conservar una redirección permanente. Prueba con curl o en una ventana privada.

Advertencia de certificado en un subdominio más profundo

Universal SSL cubre el dominio raíz y los subdominios de primer nivel. Un nombre como a.b.example.com necesita otro tipo de certificado.

Redirigir al revés (de la raíz a `www`)

Cloudflare documenta el caso inverso con la misma estructura: la regla coincide con https://example.com/* y redirige a https://www.example.com/${1}. Elige una sola dirección canónica y no combines ambas reglas.

Resumen

www no resuelve porque no tiene registro DNS; crea un registro AAAA www con contenido 100:: y proxy activado.
Las reglas de redirección de Cloudflare solo actúan sobre nombres con proxy (nube naranja).
Usa la regla "Redirect from WWW to root" (301, conservando la cadena de consulta) y activa "Always Use HTTPS"; en un dominio .app el HTTPS es obligatorio.
Evita el bucle de redirecciones: no redirijas en el origen y no uses modo "Flexible" si el origen fuerza HTTPS.
Email Routing crea los MX y el SPF, exige verificar la dirección de destino y solo gestiona correo entrante.

Referencias

Search Console: sitemap "No se ha podido obtener"

2026-11-04T15:00:00.000-05:00

Publicas un sitio nuevo, envías el sitemap en Search Console y el informe muestra un estado en rojo. Al mismo tiempo, AdSense indica que no encuentra un ads.txt que sí está publicado:

Search Console > Sitemaps
Estado: No se ha podido obtener      (en inglés: Couldn't fetch)

AdSense > Sitios
ads.txt: No encontrado               (en inglés: Not found)

Son dos avisos con causas distintas que suelen coincidir en un sitio recién creado. Aquí los separamos, comprobamos con curl que los rastreadores de Google pueden leer los archivos y vemos qué hacer (y qué no tocar) mientras Google reintenta.

Por qué pasa

La propiedad de dominio no completa la URL del sitemap. Según la ayuda de Search Console, una propiedad de dominio abarca el dominio raíz, todos sus subdominios y tanto http como https, así que no hay una única URL base con la que rellenar el campo. En una propiedad con prefijo de URL, la interfaz muestra ese prefijo delante del cuadro y basta con la ruta (por ejemplo, sitemap-index.xml); en una de dominio debes escribir la URL completa. La interfaz puede cambiar, pero la ayuda indica que el campo "Add a new sitemap" espera la URL del archivo.
"No se ha podido obtener" no siempre es un error permanente. La ayuda explica que significa que Google no pudo recuperar el archivo, y enumera causas habituales: un bloqueo en robots.txt, un error 404 o un problema temporal del servidor. También dice que algunos errores son transitorios, que Google reintenta durante unos días y que deja de intentarlo si el archivo sigue sin estar disponible. En sitios nuevos el estado puede aparecer justo después de enviar el sitemap aunque el archivo responda bien; la documentación no da una causa específica para ese caso.
AdSense todavía no volvió a revisar el archivo. En AdSense, el estado "No encontrado" significa que no halló un ads.txt en su última comprobación. La ayuda indica que los cambios pueden tardar unos días en reflejarse y hasta un mes si el sitio genera pocas solicitudes de anuncios. El archivo debe estar en la raíz del dominio (/ads.txt).

Solución

Envía el sitemap con la URL completa. En el informe Sitemaps de una propiedad de dominio, escribe la dirección entera y usa el nombre real de tu archivo (según el generador del sitio puede ser sitemap.xml, sitemap-index.xml u otro):
```
https://example.com/sitemap-index.xml
```
Ábrela antes en el navegador: debe mostrar XML, no una página de error ni una redirección a otra parte.
Comprueba qué recibe un rastreador de Google. Pide solo las cabeceras con el user agent de Googlebot y con el del rastreador de AdSense:
```
curl -I -A "Googlebot" https://example.com/sitemap-index.xml
curl -I -A "Googlebot" https://example.com/robots.txt
curl -I -A "Mediapartners-Google" https://example.com/ads.txt
```
La primera línea de cada respuesta debe indicar 200 (por ejemplo, HTTP/2 200). Para ver solo el código y el tipo de contenido, usa esta variante:
```
curl -s -o /dev/null -w "%{http_code} %{content_type}\n" -A "Googlebot" https://example.com/sitemap-index.xml
```
Un 301 o 302 indica que debes enviar la URL final (revisa la cabecera Location); un 401 o 403 suele venir de un cortafuegos o de una protección contra bots; un 404, de un archivo que no se desplegó; un 5xx, del servidor. En Windows PowerShell escribe curl.exe, porque allí curl puede ser un alias de Invoke-WebRequest, que no acepta estas opciones.

Esta prueba tiene un límite: cualquiera puede enviar un user agent falso, y Google identifica a sus rastreadores también por la IP y el DNS inverso, así que una protección que valide la IP puede tratar distinto a curl y al rastreador real. Google tampoco documenta qué rastreador descarga ads.txt; Mediapartners-Google es el de AdSense, por lo que la prueba es razonable pero no concluyente.
Revisa robots.txt. No debe bloquear el sitemap ni ads.txt. Un archivo mínimo que permite todo y anuncia el sitemap:
```
User-agent: *
Allow: /

Sitemap: https://example.com/sitemap-index.xml
```
Según la documentación de Google, un robots.txt que responde 4xx (salvo 429) se trata como si no existiera, pero uno que responde 5xx hace que Google deje de rastrear el sitio durante un tiempo: un error de servidor en ese archivo es peor que no tenerlo. Además, Mediapartners-Google ignora el grupo * y solo obedece los grupos dirigidos a su propio nombre.
Haz una prueba en vivo en Inspección de URLs. La ayuda del informe Sitemaps recomienda ejecutar la prueba en vivo y comprobar que "Page fetch" aparece como "Successful"; a diferencia de curl, usa el rastreo real de Google. Si pasa, usa "Solicitar indexación" en dos o tres páginas clave. Google aclara que no garantiza la indexación y que hay un límite diario de solicitudes.
Reenvía solo si corregiste algo. Si no había nada que arreglar, deja pasar unas horas o días: Google reintenta por su cuenta.
Prepara el ads.txt con el fragmento de AdSense. En AdSense, abre Sitios, elige el sitio y copia el fragmento de ads.txt que te ofrece, en lugar de escribir tu identificador a mano. Guárdalo como texto plano en la raíz del sitio, comprueba que https://example.com/ads.txt se muestra en el navegador y usa "Check for updates" en Sitios para pedir una nueva comprobación.
No quites el registro TXT de verificación del DNS. Una propiedad de dominio se verifica solo por DNS (salvo las alojadas por Google, como Blogger). La ayuda de Search Console indica que debes mantener ese registro aunque la verificación ya haya tenido éxito: Google lo vuelve a comprobar periódicamente y, si ya no lo encuentra, avisa y, pasado un período de gracia, caducan los permisos de la propiedad.

Cómo verificar que quedó resuelto

Los tres comandos curl del paso 2 responden 200.
En Search Console > Sitemaps, el estado del archivo pasa a "Correcto" (Success) y aparece el número de páginas descubiertas. Puede tardar horas o días.
En AdSense > Sitios, el estado de ads.txt deja de ser "No encontrado". La ayuda menciona el estado "Authorized" cuando todo está en orden.

Variantes y errores relacionados

Si tu sitio está en Blogger

Blogger genera el sitemap por ti. La ruta habitual es /sitemap.xml en la dirección de tu blog (en tu propio dominio, si lo usas). No encontré una página de la ayuda oficial de Blogger que lo documente, así que confirma que responde abriéndola en el navegador antes de enviarla. Algunas guías de terceros mencionan también /sitemap-pages.xml para las páginas estáticas; tampoco pude confirmarlo en documentación oficial, así que abre esa URL y comprueba si existe en tu blog. Según la ayuda de Search Console, en las propiedades alojadas por Google, como Blogger, la verificación es automática si inicias sesión con la cuenta que administra el blog.

Para ads.txt, la ayuda de Blogger indica que debes configurar el contenido a mano si el blog se monetiza con proveedores externos o si integraste AdSense manualmente. Los pasos son: Configuración > Monetización, activar "Enable custom ads.txt", abrir "Custom ads.txt", pegar el contenido que te da tu proveedor y guardar. Los nombres exactos del menú dependen del idioma. Para comprobarlo, abre la dirección de tu blog seguida de /ads.txt.

"Tiene errores" no es lo mismo que "No se ha podido obtener"

Con "Has errors", Google sí pudo descargar el sitemap, pero contiene errores; las URL que se leyeron bien siguen en cola de rastreo. Abre el detalle del informe para ver cada error.

Propiedad equivocada

La ayuda advierte de que el sitemap no aparece si miras la propiedad equivocada (por ejemplo, al confundir http con https, o www con la versión sin www). Una propiedad de dominio cubre todas esas variantes; aun así, las URL dentro del sitemap deben ser absolutas y usar el host canónico.

¿Hace falta un sitemap?

Google indica que no es obligatorio: un sitio de unas 500 páginas o menos y bien enlazado puede prescindir de él, y enviarlo no garantiza que todo se rastree e indexe.

Resumen

En una propiedad de dominio, escribe la URL completa del sitemap; no se completa sola.
"No se ha podido obtener" puede ser transitorio: Google reintenta durante unos días. Descarta primero un 404, un bloqueo en robots.txt o un error 5xx.
Comprueba con curl -I -A "Googlebot" y -A "Mediapartners-Google" que el sitemap, robots.txt y ads.txt responden 200, y confirma con la prueba en vivo de Inspección de URLs.
AdSense puede tardar días (hasta un mes en sitios con poco tráfico de anuncios) en reconocer el ads.txt; usa "Check for updates".
Nunca elimines el registro TXT de verificación del DNS.

Referencias

GitHub Actions: startup_failure en todos los workflows

2026-11-04T09:00:00.000-05:00

Haces push a main y el despliegue no se actualiza. En la pestaña Actions, todas las ejecuciones de todos los workflows, en todas las ramas, aparecen como fallidas sin haber ejecutado ni un solo paso. Con la CLI de GitHub, el campo conclusion de esas ejecuciones vale startup_failure:

gh run list --limit 10 --json databaseId,workflowName,headBranch,event,status,conclusion

El YAML no ha cambiado y es válido, así que reintentar las ejecuciones tampoco cambia el resultado: la causa no está en el archivo. Como tampoco hay un error en tu código, es fácil tardar días en notar que el despliegue dejó de actualizarse.

Este artículo explica qué suele estar detrás de este patrón (todos los workflows fallan al arrancar), con una causa que a veces se pasa por alto: la facturación de la cuenta. También cómo diagnosticarlo y cómo recuperar el despliegue.

Por qué pasa

La documentación de GitHub no define startup_failure en una página propia: no aparece en la referencia de la API de ejecuciones de workflows ni en la guía de solución de problemas de workflows. La CLI de GitHub sí lo incluye entre los valores que acepta gh run list --status. Por los casos reportados en la comunidad, designa ejecuciones que fallaron al arrancar, antes de ejecutar tus pasos. No es una lista completa de causas, pero estas son las que se pueden sustentar:

Un problema de facturación o de límite de gasto de la cuenta. La guía oficial de solución de problemas indica que definir un presupuesto (budget) de Actions puede desbloquear de inmediato los workflows que fallan por errores de facturación o de almacenamiento. La documentación de facturación añade que, sin un método de pago válido, el uso se bloquea cuando se agota la cuota incluida. Según la documentación de presupuestos, si se agota uno que tiene activada la opción de detener el uso, se bloquea el uso adicional (en su ejemplo, los runners alojados por GitHub, hasta el siguiente ciclo de facturación o hasta aumentar el presupuesto). Y si un pago vence por problemas de facturación, las funciones de pago de la cuenta quedan bloqueadas. En hilos de la comunidad de GitHub se reporta, en la página de la ejecución, un mensaje que dice que el job no se inició porque fallaron pagos recientes o porque hay que aumentar el límite de gasto.
Un archivo de workflow con errores de validación. Es una causa reportada en la comunidad (YAML o claves inválidas, por ejemplo). Como el defecto está en un archivo concreto, afecta a ese workflow y no a todos los demás.

La pista para distinguirlos es el alcance. Si falla un único workflow, revisa su archivo. Si fallan todos, incluidos los que no tocas desde hace meses y los de ramas antiguas, el problema está en la cuenta y no en el YAML.

Solución

Confirma el alcance con la CLI. Lista las ejecuciones recientes y filtra por el estado:
```
gh run list --limit 20 --json databaseId,workflowName,headBranch,event,status,conclusion
gh run list --status startup_failure --limit 20
```
Si todos los workflows y todas las ramas aparecen en startup_failure, sigue con el paso 2.
Abre una ejecución afectada y lee el mensaje. Desde la CLI:
```
gh run view ID_DE_EJECUCION --web
```
También puedes abrirla desde la pestaña Actions. Si el mensaje habla de pagos fallidos o de límite de gasto, pasa al paso 3.
Revisa la facturación de la cuenta. En una cuenta personal, abre github.com/settings/billing; en una organización, entra en su página Billing & Licensing. Comprueba lo siguiente:
- Método de pago: que no haya vencido y que el último cargo no se haya rechazado. Según la documentación sobre tarjetas rechazadas, tras un cargo rechazado GitHub envía un correo con el motivo y da unos días para resolverlo antes de volver a intentar el cobro.
- Restricciones del banco: esa misma página señala que algunos bancos internacionales restringen las transacciones internacionales, de comercio electrónico y recurrentes automáticas. Si el cargo falla sin otra explicación, consulta con tu banco.
- Presupuestos: en Budgets and alerts, mira si hay un presupuesto de Actions con la opción de detener el uso al alcanzar el límite.
- Cuenta bloqueada: si la cuenta quedó bloqueada por un pago vencido, actualiza el método de pago. La documentación indica que se desbloquea sola cuando un pago se procesa con éxito, y que el proceso puede tardar hasta 24 horas.
Cuando el pago esté resuelto, lanza una ejecución nueva. Basta con un push o un pull request. Para poder lanzar el despliegue a mano, añade workflow_dispatch al disparador y fusiona el cambio en la rama predeterminada (según la documentación de ejecución manual, el workflow debe estar en esa rama para recibir el evento):
```
on:
  push:
    branches: [main]
  workflow_dispatch:
```
Después, desde la CLI (el nombre es el del workflow, o su archivo):
```
gh workflow run "Deploy" --ref main
```
Mientras el bloqueo siga activo, es de esperar que ni un push nuevo ni gh run rerun cambien el resultado, porque la causa no está en el workflow. Conviene añadir workflow_dispatch antes de necesitarlo.

Cómo verificar que quedó resuelto

gh run list --workflow "Deploy" --branch main --limit 5

Las ejecuciones nuevas deben terminar con conclusion igual a success en lugar de startup_failure. Después, comprueba el efecto real del despliegue: que el servicio sirve la versión nueva (por ejemplo, por el identificador del build o la fecha de reinicio de los contenedores), no solo que el workflow esté en verde. Si el bloqueo era de facturación y se corrigió, es lo esperable: el mismo workflow, sin cambios, vuelve a ejecutarse.

Variantes y errores relacionados

No se crea ninguna ejecución

Es otro síntoma, con otras causas. La guía de solución de problemas menciona que un workflow desactivado no responde a sus disparadores, que los filtros de rama, etiqueta o ruta pueden omitir la creación de la ejecución, que los workflows de pull_request no se ejecutan si el pull request tiene un conflicto de fusión, y que eventos como schedule solo se ejecutan desde la rama predeterminada.

Solo un workflow en `startup_failure`

Revisa su archivo: según los casos reportados en la comunidad, un error de validación puede hacer que la ejecución termine así. Abre la ejecución y lee el mensaje que muestra la página. Si no ayuda, prueba con un workflow mínimo en una rama de pruebas para ver si el fallo depende del archivo o de la cuenta.

Prevenir el siguiente bloqueo

La documentación de presupuestos describe alertas al 75 %, 90 % y 100 % del presupuesto, por correo y como aviso en GitHub, y la de facturación de Actions describe avisos por correo cuando el uso incluido llega al 90 % y al 100 %. Actívalas, y añade una notificación (correo o chat) cuando falle el workflow de despliegue, para no descubrir el problema días después.

Resumen

startup_failure en todos los workflows y ramas, con el YAML intacto, apunta a un problema de cuenta y no a tu código.
GitHub documenta que la facturación puede bloquear el uso de Actions: método de pago ausente o vencido, presupuesto agotado o cuenta bloqueada por un pago vencido.
Revisa github.com/settings/billing (o Billing & Licensing en una organización): método de pago, cargos rechazados y presupuestos.
Cuando se resuelva, lanza una ejecución nueva (push, pull request o gh workflow run con workflow_dispatch); un reintento no cambia la causa mientras siga el bloqueo.
Verifica con gh run list que la conclusión sea success y que el servicio sirva la versión nueva.

Referencias

Node: Cannot find module con un script fuera del proyecto

2026-11-03T15:00:00.000-05:00

Escribes un script rápido para probar algo (una consulta a la base de datos, una conexión WebSocket) y lo guardas en una carpeta temporal. La dependencia está instalada en tu proyecto y ejecutas el script desde la carpeta del proyecto, pero Node responde con uno de estos errores. En CommonJS (require):

Error: Cannot find module 'pg'
Require stack:
- C:\temp\prueba\test.cjs

En módulos ES (import, archivos .mjs):

Error [ERR_MODULE_NOT_FOUND]: Cannot find package 'ws' imported from C:\temp\prueba\test.mjs

Este artículo explica dónde busca Node los paquetes, por qué la carpeta desde la que ejecutas no cuenta, y las cuatro formas de resolverlo.

Por qué pasa

La documentación de Node explica que, para un nombre de paquete (un identificador que no empieza por /, ./ ni ../), Node parte del directorio del archivo que lo importa, añade /node_modules y busca ahí. Si no lo encuentra, sube al directorio padre y repite, hasta llegar a la raíz del sistema de archivos. La carpeta desde la que lanzas el comando (el directorio de trabajo) no interviene.

Para un script en C:\temp\prueba, Node mira C:\temp\prueba\node_modules, luego C:\temp\node_modules y C:\node_modules. Tu proyecto no está en esa cadena, así que no importa que node_modules exista en otra parte. La resolución de módulos ES describe el mismo recorrido: busca node_modules/nombre a partir de la URL del archivo que importa y va subiendo por las carpetas padre. Lo hace Node, no el gestor de paquetes: npm o pnpm solo deciden qué hay dentro de cada node_modules.

Los dos sistemas difieren en NODE_PATH:

Dónde busca	CommonJS (`require`)	Módulos ES (`import`)
`node_modules` desde la carpeta del archivo y sus padres	sí	sí
Directorio de trabajo del comando	no	no
Variable `NODE_PATH`	sí, si no se encuentra antes	no

La documentación indica para CommonJS que, si el módulo no se encuentra en otro sitio, Node recorre las rutas de NODE_PATH, y para módulos ES que NODE_PATH no forma parte de la resolución de import y recomienda usar enlaces simbólicos. Las pruebas locales con Node 24 coincidieron con la tabla.

Solución

Confirma qué carpetas está mirando Node. En un script CommonJS, require.resolve.paths devuelve las rutas que se buscan para un nombre:
```
console.log(require.resolve.paths("pg"));
```
La primera ruta es node_modules junto al script, seguida de las de sus carpetas padre; ninguna es la de tu proyecto. Para comprobar que la dependencia sí está instalada en el proyecto, ejecuta esto desde su carpeta (en la prueba, con -e la búsqueda partió del directorio actual):
```
node -e "console.log(require.resolve('pg'))"
```
Debe imprimir una ruta dentro del node_modules del proyecto. Si falla con MODULE_NOT_FOUND, el paquete no está instalado ahí: instálalo (npm install pg o el comando equivalente de tu gestor) y repite.
La opción más simple: coloca el script dentro del proyecto. Guárdalo con un nombre temporal, por ejemplo .tmp-prueba.mjs, en la raíz (o en una subcarpeta) del proyecto, ejecútalo y bórralo:
```
node .tmp-prueba.mjs
```
Desde ahí, la cadena de búsqueda sí incluye el node_modules del proyecto. Antes de confirmar cambios en Git, revisa que el archivo temporal no quede en el commit (por ejemplo, añade el patrón .tmp-* a .gitignore).
Si el script debe seguir fuera: resuelve desde el proyecto con createRequire. module.createRequire crea una función require anclada a un archivo (ruta absoluta o URL de archivo). Si la anclas al package.json del proyecto, busca los paquetes desde esa carpeta. Funciona en CommonJS y en módulos ES:
```
import { createRequire } from "node:module";
import path from "node:path";
const raiz = process.env.RAIZ_PROYECTO;
const requireDesdeProyecto = createRequire(path.join(raiz, "package.json"));
const { hola } = requireDesdeProyecto("mi-paquete");
console.log("mjs createRequire:", hola());
```
Ejecútalo indicando la carpeta del proyecto en una variable de entorno (PowerShell, solo para esa sesión):
```
$env:RAIZ_PROYECTO = "C:\proyectos\mi-app"
node C:\temp\prueba\crear.mjs
```
En CommonJS el código es el mismo, cambiando la primera línea por const { createRequire } = require("node:module");. Si necesitas un paquete como módulo ES, resuelve la ruta con createRequire e impórtala con import() mediante una URL de archivo:
```
import { pathToFileURL } from "node:url";
import { createRequire } from "node:module";
import path from "node:path";
const raiz = process.env.RAIZ_PROYECTO;
const req = createRequire(path.join(raiz, "package.json"));
const ruta = req.resolve("mi-paquete");
const paquete = await import(pathToFileURL(ruta).href);
console.log("mjs import(resolve):", paquete.default.hola());
```
Un matiz: req.resolve usa las reglas de require. En paquetes que declaran entradas distintas para require e import en su campo exports, puede devolver la entrada de require.
Solo en CommonJS: usa NODE_PATH. Apunta a la carpeta node_modules del proyecto. En PowerShell:
```
$env:NODE_PATH = "C:\proyectos\mi-app\node_modules"
node C:\temp\prueba\test.cjs
Remove-Item Env:NODE_PATH
```
En Bash:
```
NODE_PATH=/home/usuario/mi-app/node_modules node /tmp/prueba/test.cjs
```
Según la documentación, varias rutas se separan con ; en Windows y con : en el resto de plataformas. Este mecanismo no sirve para import (ver más abajo), y la propia documentación indica que hoy es menos necesario.
Para CommonJS y módulos ES: enlaza o instala junto al script. Un enlace llamado node_modules al lado del script hace que la búsqueda lo encuentre. En Windows se puede usar una unión (junction); en la prueba se creó desde una sesión de PowerShell sin permisos de administrador. En Linux o macOS, un enlace simbólico:
```
New-Item -ItemType Junction -Path C:\temp\prueba\node_modules -Target C:\proyectos\mi-app\node_modules
```
```
ln -s /home/usuario/mi-app/node_modules /tmp/prueba/node_modules
```
En la prueba con Windows, la unión hizo que funcionaran tanto el script CommonJS como el de módulos ES. La variante con ln -s sigue el mismo principio, pero no se probó. Al terminar, elimina solo el enlace, nunca su destino: (Get-Item C:\temp\prueba\node_modules).Delete() quitó el enlace y dejó intacto el paquete original. La alternativa es instalar la dependencia en la carpeta del script (npm install pg allí), a costa de duplicarla.

Cómo verificar que quedó resuelto

Con cualquiera de las opciones, ejecuta el script que fallaba desde la carpeta del proyecto y desde otra distinta; el resultado debe ser el mismo, porque el directorio de trabajo no influye:

node --version
node C:\temp\prueba\crear.mjs

En la reproducción local (Node 24, un paquete de prueba en el node_modules de un proyecto de juguete), estos fueron los resultados:

Script de CommonJS y de módulos ES en una carpeta hermana, ejecutados desde el proyecto: Cannot find module y ERR_MODULE_NOT_FOUND.
Los mismos scripts copiados dentro del proyecto: se ejecutaron bien.
createRequire (en .cjs y .mjs) y import() con la ruta resuelta: bien.
NODE_PATH: bien en CommonJS; el script .mjs siguió fallando.
Unión de Windows al node_modules del proyecto: bien en ambos.

Variantes y errores relacionados

`NODE_PATH` definido y un mensaje engañoso en `import`

Con NODE_PATH apuntando al proyecto, el script .mjs falló con el mismo ERR_MODULE_NOT_FOUND y añadió la pista Did you mean to import "mi-paquete/index.js"?. Esa sugerencia no funciona: probar import "mi-paquete/index.js" falló igual, porque la resolución de import ignora NODE_PATH.

`Cannot find module` frente a `Cannot find package` en `import`

Con un paquete, el mensaje dice Cannot find package 'x' imported from .... Con una ruta relativa sin extensión (import "./otro") dice Cannot find module '...\otro' imported from .... La documentación de módulos ES indica que la resolución por defecto no añade extensiones: escribe ./otro.js.

Monorepos

Por la misma regla de recorrido hacia arriba, un script dentro de packages/api encuentra las dependencias en el node_modules de la raíz del repositorio si no están en packages/api/node_modules.

Códigos de error

Según la documentación de errores de Node, MODULE_NOT_FOUND es el código que usa el cargador de CommonJS y ERR_MODULE_NOT_FOUND el de módulos ES, para un módulo que no se pudo resolver.

Resumen

Node busca los paquetes en node_modules a partir de la carpeta del archivo que los importa y sube por las carpetas padre; el directorio de trabajo no cuenta.
Lo más simple es colocar el script dentro del proyecto (por ejemplo .tmp-prueba.mjs) y borrarlo después.
createRequire anclado al package.json del proyecto resuelve los paquetes desde allí, en CommonJS y en módulos ES.
NODE_PATH solo funciona con require, no con import.
Un enlace node_modules junto al script (unión en Windows, enlace simbólico en Linux o macOS) o una instalación local también lo resuelven.

Referencias

Git: rama divergida y conflictos tras squash and merge

2026-11-03T09:00:00.000-05:00

Trabajas con ramas permanentes (por ejemplo feature hacia develop, luego qa y por último main) y fusionas cada PR con "Squash and merge". Después de fusionar, aparecen tres síntomas:

La rama local figura como divergida de develop aunque el contenido es idéntico.
El siguiente PR desde la misma rama lista archivos que ya habías fusionado, o informa conflictos.
Un PR de qa hacia main marca conflictos en archivos que main no ha tocado desde la última promoción.

El primer síntoma se ve así en Git. Ocurre, por ejemplo, con una rama creada con git switch -c feature/x origin/develop, que por defecto hereda origin/develop como rama de seguimiento, después de que develop recibió el squash de sus 2 commits:

On branch feature/x
Your branch and 'origin/develop' have diverged,
and have 2 and 1 different commits each, respectively.

Este artículo explica por qué ocurre, cómo comprobar que no se perdió nada y cómo resincronizar la rama para que los PR siguientes vuelvan a mostrar solo tus cambios.

Por qué pasa

Según la documentación de GitHub, "Squash and merge" combina todos los commits del PR en un único commit nuevo sobre la rama base. Ese commit tiene su propio hash y solo un padre: los commits originales de tu rama (F1, F2) nunca llegan a la rama base.

develop:  B ---------------- S     (S: un commit nuevo, sin relación con F1 ni F2)
           \
feature:    F1 -- F2                (siguen siendo commits distintos de S)

El contenido es el mismo, pero para Git son historias distintas. Git no compara commit por commit; al fusionar, según su documentación, solo considera las dos puntas y la base de fusión (el último ancestro común). Tras el squash, esa base sigue siendo B, el punto donde la rama se separó. De ahí salen los síntomas:

GitHub muestra en un PR una diferencia de tres puntos: compara la base de fusión con la punta de la rama. Con la base antigua, los cambios ya fusionados vuelven a aparecer. La propia documentación de GitHub avisa de que, si sigues trabajando en la misma rama y abres otro PR hacia la misma base, los commits que ya combinaste se listan de nuevo y puede que debas resolver los mismos conflictos una y otra vez.
Si después de la fusión vuelves a editar las mismas líneas, el cambio de la rama base (S) y el tuyo parten de la versión antigua B, así que Git ve dos ediciones distintas de la misma línea y marca conflicto.
En develop, qa y main, que se reutilizan en cada ciclo, el efecto se repite en cada promoción: el squash que entra en main nunca aparece en la historia de qa.

Por la misma razón, las herramientas que comparan commits no sirven para saber si algo ya está integrado: en la prueba, git cherry -v origin/develop HEAD marcó con + los dos commits, porque ninguno coincide con el commit de squash. Compara contenido, como en el primer paso de la solución.

Solución

Comprueba que el contenido es idéntico. Justo después de cada squash merge:
```
git fetch origin
git diff origin/develop --stat
```
Si no imprime nada, tu rama y develop tienen exactamente los mismos archivos y puedes resincronizar sin perder trabajo. Si imprime archivos, hay cambios locales que aún no están en develop: no resincronices a ciegas.
Resincroniza la rama. Fusiona origin/develop en tu rama:
```
git merge origin/develop
```
Como ambos lados contienen los mismos cambios, la fusión se completa sin conflictos (en la reproducción local así fue) y la base de fusión pasa a ser la punta de develop. Los PR siguientes solo mostrarán los commits nuevos. Si no necesitas conservar los commits antiguos, también puedes crear la rama de nuevo desde el remoto:
```
git switch -c feature/x-2 origin/develop
```
git reset --hard origin/develop deja el mismo resultado, pero descarta cualquier cambio local sin guardar; úsalo solo cuando el paso 1 salió vacío y no tienes nada pendiente.
Comprueba la fusionabilidad antes de pedir revisión. En local, git merge-tree simula la fusión sin tocar tu directorio de trabajo ni el índice:
```
git merge-tree --write-tree --name-only origin/develop HEAD
```
El código de salida es 0 si la fusión es limpia y 1 si hay conflictos; en ese caso imprime los archivos en conflicto. (Según su documentación, no crea commits ni lee o escribe el directorio de trabajo o el índice; solo genera un objeto de árbol. El modo --write-tree existe en versiones recientes de Git; la prueba usó la 2.54.) En GitHub, justo después de abrir el PR:
```
gh pr view NUMERO --json mergeable,mergeStateStatus
```
Según la referencia de la API GraphQL, MERGEABLE indica que se puede fusionar, CONFLICTING que tiene conflictos y UNKNOWN que aún se está calculando; en mergeStateStatus, CLEAN significa que se puede fusionar y las comprobaciones pasan, y DIRTY que la fusión no se puede crear sin conflictos. Si ves UNKNOWN, repite la consulta unos segundos después.
Para un PR de qa a main con conflictos, crea una rama de sincronización desde main. Necesitas el SHA del commit de qa que se promovió la última vez (por ejemplo, el último commit del PR anterior). En Git Bash o WSL:
```
git fetch origin
ABSORBIDO=SHA_DE_QA_DE_LA_ULTIMA_PROMOCION
git switch -c sync/qa-main origin/main
git merge origin/qa

git diff --name-only --diff-filter=U | while IFS= read -r f; do
  actual=$(git rev-parse -q --verify "origin/main:$f")
  absorbido=$(git rev-parse -q --verify "$ABSORBIDO:$f")
  if [ -n "$actual" ] && [ "$actual" = "$absorbido" ]; then
    git checkout --theirs -- "$f" && git add -- "$f"
  else
    echo "REVISAR a mano: $f"
  fi
done
git commit --no-edit
```
La lógica: si el contenido de un archivo en main es idéntico (mismo hash de blob) al que tenía qa cuando se promovió por última vez, main no lo ha cambiado desde entonces y la versión correcta es la de qa. En una fusión, --theirs es la rama que fusionas (qa). Si los hashes difieren, main tiene cambios propios y debes resolver ese archivo a mano.

Evita el atajo git merge -X theirs origin/qa: según la documentación, resuelve a favor del otro lado todos los trozos en conflicto, incluidos los que contienen una corrección real hecha en main.
Cambia el método de fusión en las promociones entre ramas permanentes. Mientras develop → qa → main se fusionen con squash, el problema volverá en el ciclo siguiente. Con "Create a merge commit", GitHub añade todos los commits de la rama de origen a la base mediante un commit de fusión, de modo que la base de fusión avanza. Mantén "Squash and merge" para feature → develop, donde la rama se descarta tras fusionar. Esto exige que el repositorio permita ese método de fusión y deja commits de fusión en la historia.

Cómo verificar que quedó resuelto

Tras resincronizar tu rama, el primer número de este comando (commits que solo están en develop) debe ser 0:

git rev-list --left-right --count origin/develop...HEAD
git diff --stat origin/develop...HEAD

El segundo comando es lo que verá el PR: en la reproducción local, antes de resincronizar listaba 2 archivos (uno de ellos ya fusionado por el squash) y, después de resincronizar, solo el archivo del commit nuevo. En el mismo caso, git merge-tree pasó de terminar con código 1 (conflicto en el archivo editado dos veces) a terminar con código 0.

En la rama de sincronización qa → main, comprueba que el árbol resultante coincide con el de qa:

git rev-parse "HEAD^{tree}"
git rev-parse "origin/qa^{tree}"

Los dos hashes deben ser iguales. En PowerShell las comillas son necesarias: sin ellas, HEAD^{tree} falló en la prueba con Windows PowerShell 5.1. Si main recibió cambios que qa no tiene (por ejemplo, una corrección urgente), los árboles diferirán justo en esos archivos; revisa con git diff --stat origin/qa HEAD que solo aparecen ellos. Por último, una vez abierto el PR de sincronización, gh pr view debe mostrar MERGEABLE y, si las comprobaciones pasan, CLEAN. Esa parte depende de GitHub y no se reprodujo en local: la reproducción usó repositorios locales que simulan el squash con git merge --squash.

Variantes y errores relacionados

`error: the branch 'feature/x' is not fully merged`

Después del squash, si la rama remota se borró (y se ejecutó git fetch --prune), git branch -d feature/x responde con ese error aunque el contenido esté en develop: así ocurrió en la prueba con Git 2.54, con develop actualizada y como rama actual. Comprueba primero que git diff develop feature/x --stat no imprime nada y entonces usa git branch -D feature/x.

Conflictos de tipo "modificado/eliminado"

Si un archivo se creó o se borró en uno de los lados, git rev-parse -q --verify no devuelve ningún hash para él. El script lo marca como "REVISAR a mano" en lugar de tomar una decisión por ti.

El mismo problema en `develop` → `qa`

No es exclusivo de main. Cualquier promoción por squash entre dos ramas que siguen vivas acumula la misma divergencia; la receta de la rama de sincronización sirve para cualquier par de ramas.

Resumen

"Squash and merge" crea un commit nuevo en la rama base; tus commits originales no entran en su historia, aunque el contenido sea idéntico.
Tras cada squash, ejecuta git fetch origin y git diff origin/develop --stat: vacío significa mismo contenido.
Resincroniza enseguida con git merge origin/develop (o recrea la rama desde el remoto) para que los PR muestren solo tus archivos.
Para qa → main, fusiona origin/qa en una rama creada desde origin/main y resuelve por archivo comparando hashes de blob; verifica con los hashes de árbol.
Para romper el ciclo, usa "Create a merge commit" en las promociones entre ramas permanentes.

Referencias

Zod: Invalid enum value, received '' al leer Excel

2026-11-02T15:00:00.000-05:00

Subes un archivo de Excel correcto, con una columna opcional que quedó vacía en todas las filas, y el servidor rechaza cada fila. Al validar con Zod aparece este error (Zod 3):

[
  {
    "received": "",
    "code": "invalid_enum_value",
    "options": ["a", "b"],
    "path": ["tipo"],
    "message": "Invalid enum value. Expected 'a' | 'b', received ''"
  }
]

En Zod 4 el mensaje cambia a Invalid option: expected one of "a"|"b" (con el código invalid_value), pero la causa es la misma. El esquema parece correcto, porque la columna tiene un valor por defecto:

const Fila = z.object({
  nombre: z.string(),
  tipo: z.enum(["a", "b"]).default("a"),
});

const filas = XLSX.utils
  .sheet_to_json(hoja, { defval: "" })
  .map((fila) => Fila.parse(fila));

Este artículo explica por qué el valor por defecto nunca se aplica, cuándo usar ?? y cuándo ||, y cómo normalizar las celdas vacías con y sin Zod.

Por qué pasa

El fallo es la suma de tres comportamientos que, por separado, son correctos:

defval: "" convierte las celdas vacías en cadenas vacías. En la documentación de SheetJS, defval sustituye los valores null o undefined; sin esa opción, las celdas vacías se omiten y la clave no existe en el objeto. Leyendo un .xlsx con una celda vacía, sheet_to_json(hoja) devolvió {"nombre":"ana"} y, con defval: "", {"nombre":"ana","tipo":""}.
?? solo reemplaza null y undefined. Según MDN, la cadena vacía y el 0 son valores válidos para este operador: "" ?? "a" devuelve "".
.default() de Zod solo actúa con undefined. La documentación indica que, si la entrada es undefined, se devuelve el valor por defecto. Una cadena vacía es una cadena, así que pasa al z.enum, que no la acepta.

Resultado observado con Zod 3.25 y con Zod 4.6 (misma conducta en ambas):

Entrada para `tipo`	Con `.default("a")`
clave ausente o `undefined`	devuelve `"a"`
`""`	error de enum
`null` (probado con Zod 4)	error de enum

Con ExcelJS el patrón es distinto. Según su documentación, row.eachCell() visita solo las celdas no nulas, y con { includeEmpty: true } visita también las vacías. En la prueba, el valor de una celda vacía fue null, no una cadena vacía, de modo que ahí ?? sí funciona, pero .default() tampoco se aplica a null.

Solución

Normaliza la celda en el punto de lectura. Convierte a texto, recorta espacios y sustituye lo vacío por el valor por defecto:
```
export function tipoDesdeCelda(valor: unknown, porDefecto = "a"): string {
  return String(valor ?? "").trim() || porDefecto;
}
```
Cada operador tiene un trabajo. ?? "" evita que String(null) produzca el texto "null". trim() trata una celda con solo espacios como vacía. || reemplaza la cadena vacía resultante, que es justo lo que se busca aquí. El número 0 no se pierde: String(0) es "0", una cadena no vacía.

Regla práctica: usa ?? cuando 0, "" o false son valores legítimos que no debes tocar; usa || cuando "vacío" significa "usa el valor por defecto" (y convierte antes a texto si el dato puede ser un número).

O deja que Zod haga la normalización con z.preprocess. Convierte la cadena vacía en undefined antes del enum, y el .default() interno ya funciona:

import * as XLSX from "xlsx";
import { z } from "zod";

const vacioComoUndefined = (valor: unknown): unknown =>
  typeof valor === "string" && valor.trim() === "" ? undefined : valor;

export const FilaSchema = z.object({
  nombre: z.string().min(1),
  tipo: z.preprocess(vacioComoUndefined, z.enum(["a", "b"]).default("a")),
});

export type Fila = z.infer<typeof FilaSchema>;

export function leerFilas(hoja: XLSX.WorkSheet): Fila[] {
  const crudas = XLSX.utils.sheet_to_json<Record<string, unknown>>(hoja, { defval: "" });
  return crudas.map((fila) => FilaSchema.parse(fila));
}

Un valor inválido como "x" sigue rechazándose, que es lo deseable. Evita .catch("a") para este caso: oculta también los errores reales de datos. Tampoco sirve .optional(), porque "" no es undefined.

Si no necesitas defval, quítalo. Sin esa opción, SheetJS omite las celdas vacías y la clave llega ausente, de modo que .default("a") funciona sin preprocess. Mantén defval solo si necesitas que todas las claves existan en cada fila.

Cómo verificar que quedó resuelto

Estas pruebas generan un .xlsx en memoria, lo leen de nuevo y comprueban los cuatro comportamientos que importan:

import { test } from "node:test";
import assert from "node:assert/strict";
import * as XLSX from "xlsx";
import { leerFilas, tipoDesdeCelda } from "./leer-excel.ts";

/** Crea una hoja, la guarda como .xlsx en memoria y la vuelve a leer. */
function hojaDesde(filas: unknown[][]): XLSX.WorkSheet {
  const libro = XLSX.utils.book_new();
  XLSX.utils.book_append_sheet(libro, XLSX.utils.aoa_to_sheet(filas), "Hoja1");
  const archivo = XLSX.write(libro, { type: "buffer", bookType: "xlsx" });
  return XLSX.read(archivo).Sheets["Hoja1"];
}

test("celda vacía usa el valor por defecto", () => {
  const filas = leerFilas(hojaDesde([["nombre", "tipo"], ["ana", null], ["luis", "b"]]));
  assert.deepEqual(filas, [{ nombre: "ana", tipo: "a" }, { nombre: "luis", tipo: "b" }]);
});

test("celda con solo espacios usa el valor por defecto", () => {
  const filas = leerFilas(hojaDesde([["nombre", "tipo"], ["ana", "   "]]));
  assert.equal(filas[0].tipo, "a");
});

test("un valor inválido sigue rechazándose", () => {
  assert.throws(() => leerFilas(hojaDesde([["nombre", "tipo"], ["ana", "x"]])));
});

test("tipoDesdeCelda cubre null, undefined, vacío y números", () => {
  assert.equal(tipoDesdeCelda(null), "a");
  assert.equal(tipoDesdeCelda(undefined), "a");
  assert.equal(tipoDesdeCelda(""), "a");
  assert.equal(tipoDesdeCelda("  b "), "b");
  assert.equal(tipoDesdeCelda(0), "0");
});

node --test leer-excel.test.ts
npx tsc --noEmit

En la reproducción local (Node 24, xlsx 0.18.5, Zod 3.25 y Zod 4.6) las cuatro pruebas pasaron y tsc terminó sin errores. El esquema con z.preprocess dio el mismo resultado en las dos versiones de Zod. Revisa también, uno por uno, los demás lugares donde tu proyecto lee archivos de Excel o CSV: cualquier parser que use un valor por defecto de cadena vacía y luego ?? tiene el mismo problema.

Variantes y errores relacionados

Columnas numéricas: la cadena vacía se convierte en 0

Según la documentación de Zod, z.coerce.number() convierte la entrada con Number(entrada), y Number("") es 0, así que una celda vacía pasa como 0 sin ningún error (probado en Zod 3 y 4). Si "vacío" debe significar "sin dato", pasa primero la entrada por la misma función vacioComoUndefined y marca el campo como .optional().

`defval: null`

Con null en lugar de "", .default() tampoco actúa. En la prueba, un preprocess que convierte tanto null como las cadenas en blanco en undefined funcionó en Zod 3 y 4:

const blancoAUndefined = (v: unknown): unknown =>
  v === null || (typeof v === "string" && v.trim() === "") ? undefined : v;

ExcelJS: celdas vacías al final de la fila

En la prueba, row.eachCell({ includeEmpty: true }) visitó la celda vacía del medio de una fila (valor null), pero no la celda vacía final, porque la fila no la almacena. Para obtener siempre las columnas por posición usa row.getCell(n).value, que devuelve null si no hay valor.

Celdas con solo espacios

Para el usuario parecen vacías, pero " " || "a" devuelve los espacios. Por eso el patrón incluye trim().

Resumen

sheet_to_json(hoja, { defval: "" }) produce "" en las celdas vacías, y ni ?? ni .default() de Zod reaccionan a una cadena vacía.
?? solo cubre null y undefined; úsalo cuando 0 o "" sean valores válidos.
Cuando "vacío" significa "valor por defecto", normaliza con String(x ?? "").trim() || valorPorDefecto.
Con Zod, usa z.preprocess para convertir las cadenas en blanco en undefined antes del .default(); funciona en Zod 3 y 4.
Vigila las columnas numéricas: z.coerce.number() convierte "" en 0.

Referencias

JavaScript: la suma de porcentajes da 0.9999999999999999

2026-11-02T09:00:00.000-05:00

Tienes un reparto entre varios miembros (porcentajes de participación, cuotas o pesos). La interfaz indica que está completo, pero el motor de validación lo rechaza con un mensaje como este:

Error: El reparto debe sumar 1 (suma actual: 0.9999999999999999)

La causa se reproduce con diez miembros que reciben 0.1 cada uno:

const partes = Array(10).fill(0.1);
const suma = partes.reduce((acc, p) => acc + p, 0);

console.log(suma);       // 0.9999999999999999
console.log(suma === 1); // false

Este artículo explica por qué ocurre, cómo validar con una tolerancia adecuada (y por qué Number.EPSILON no basta para sumas acumuladas) y cómo repartir en unidades enteras para que el total sea exacto.

Por qué pasa

Según MDN, el tipo Number de JavaScript es un valor IEEE 754 de doble precisión y 64 bits en formato binario. Una fracción decimal como 0.1 no tiene representación binaria finita, así que se almacena el valor más cercano que cabe en 64 bits. Cada suma vuelve a redondear el resultado y esos errores diminutos se acumulan. El ejemplo clásico es este:

0.1 + 0.2;          // 0.30000000000000004
0.1 + 0.2 === 0.3;  // false

En un reparto, el resultado depende del número de miembros y de la escala. Sumando N veces el valor 100/N (en porcentaje) y N veces ese mismo valor dividido entre 100 (como fracción), Node 24 devolvió esto:

Miembros (N)	Suma en porcentaje	Suma como fracción
3	100	1
6	100.00000000000001	1.0000000000000002
7	100.00000000000001	1.0000000000000002
10	100	0.9999999999999999
11	100.00000000000001	1.0000000000000002
13	100	0.9999999999999998

Con 3 miembros todo parece correcto y con 11 la suma no es exactamente 1. Como el resultado cambia con N y con la escala, el fallo parece aleatorio, pero es determinista.

Redondear cada parte a dos decimales tampoco cierra el total: 3 partes de 33.33 suman 99.99 y 6 partes de 16.67 suman 100.02. Eso ya no es un problema de coma flotante sino de redondeo, y se resuelve repartiendo el resto (paso 2).

Hay un tercer culpable, que no es de precisión. Si el valor viaja entre capas como porcentaje y alguna capa lo divide entre 100 sin que otra lo sepa, dos mitades de 50 % suman 1 con una división (0.5 + 0.5) y 0.01 con dos divisiones (0.005 + 0.005). Una tolerancia no debe tapar ese error (paso 3).

Solución

Compara con una tolerancia en lugar de usar ===. Define una constante y úsala en toda la validación:
```
/** Tolerancia absoluta: mucho mayor que el error de coma flotante y mucho menor que 0,01 %. */
export const TOLERANCIA = 1e-6;

export interface ResultadoReparto {
  valido: boolean;
  suma: number;
  mensaje?: string;
}

/** Valida que las participaciones (fracciones entre 0 y 1) sumen 1 dentro de TOLERANCIA. */
export function validarReparto(
  participaciones: ReadonlyArray<number | null | undefined>,
): ResultadoReparto {
  const suma = participaciones.reduce<number>((acc, p) => acc + (p ?? 0), 0);
  if (!Number.isFinite(suma) || Math.abs(suma - 1) >= TOLERANCIA) {
    return {
      valido: false,
      suma,
      mensaje: `El reparto debe sumar 1 (suma actual: ${suma})`,
    };
  }
  return { valido: true, suma };
}
```
El valor 1e-6 es órdenes de magnitud mayor que el error de coma flotante de unas pocas sumas (del orden de 1e-16) y mucho menor que la diferencia más pequeña que una persona puede introducir: 0.01 % equivale a 1e-4 como fracción. Ajústalo a la precisión real de tus datos.

¿Por qué no Number.EPSILON? MDN lo define como la diferencia entre 1 y el siguiente número representable (unos 2.22e-16), lo que lo hace útil para valores cercanos a 1 y para el error de una sola operación, y advierte que no debe usarse sin más como umbral de igualdad. En sumas acumuladas se queda corto. En la prueba, once sumandos de 1/11 se alejan de 1 exactamente en Number.EPSILON, así que Math.abs(suma - 1) < Number.EPSILON da false; y cien sumandos de 0.01 dan 1.0000000000000007, unas tres veces esa diferencia.

Reparte en unidades enteras (puntos básicos) con el método del mayor resto. Si la interfaz y el motor trabajan con enteros, la suma es exacta por construcción: MDN indica que los enteros se representan sin pérdida entre −(2⁵³ − 1) y 2⁵³ − 1. Usa 10 000 puntos básicos como 100 %:

/**
 * Reparte `total` unidades enteras (por defecto 10 000 puntos básicos = 100 %)
 * proporcionalmente a `pesos`, con el método del mayor resto.
 * La suma del resultado es exactamente `total`.
 */
export function repartirEnteros(pesos: readonly number[], total = 10_000): number[] {
  const sumaPesos = pesos.reduce((acc, p) => acc + p, 0);
  if (pesos.length === 0 || !(sumaPesos > 0)) {
    throw new Error("Se necesita al menos un peso positivo");
  }
  const cuotas = pesos.map((p) => (p / sumaPesos) * total);
  const partes = cuotas.map((c) => Math.floor(c));
  let resto = total - partes.reduce((acc, n) => acc + n, 0);
  const orden = cuotas
    .map((c, i) => ({ i, fraccion: c - Math.floor(c) }))
    .sort((a, b) => b.fraccion - a.fraccion || a.i - b.i);
  for (let k = 0; resto > 0; k = (k + 1) % orden.length) {
    partes[orden[k].i] += 1;
    resto -= 1;
  }
  return partes;
}

El método toma la parte entera de cada cuota y entrega las unidades sobrantes, de una en una, a quienes tienen la mayor parte decimal. El desempate por posición lo hace determinista. Con 11 miembros iguales, diez reciben 909 y uno recibe 910: suman 10 000. Convierte a porcentaje solo para mostrar:

/** Solo para mostrar: 3333 -> "33,33 %". */
export function formatearPuntosBasicos(pb: number): string {
  return `${(pb / 100).toFixed(2).replace(".", ",")} %`;
}

Usa una sola escala y convierte una vez. Decide si el dato viaja como fracción (0 a 1), como porcentaje (0 a 100) o como puntos básicos, y refléjalo en el nombre del campo (participacionPb, fraccion). Convierte únicamente en los bordes: al recibir lo que escribe el usuario y al mostrarlo. Si la suma sale 0.01 o 0.0001 en lugar de 1, busca la división repetida; no aumentes la tolerancia.

Escribe pruebas que fallarían con ===. Estas nueve usan node:test; los fixtures de los casos 2 y 3 comprueban primero que la comparación estricta realmente falla:

import { test } from "node:test";
import assert from "node:assert/strict";
import { formatearPuntosBasicos, repartirEnteros, TOLERANCIA, validarReparto } from "./reparto.ts";

const suma = (xs: number[]) => xs.reduce((a, b) => a + b, 0);

test("1. suma exacta es válida", () => {
  assert.equal(validarReparto([0.25, 0.25, 0.25, 0.25]).valido, true);
});

test("2. diez veces 0.1 es válida aunque la suma no sea exactamente 1", () => {
  const partes = Array<number>(10).fill(0.1);
  assert.notEqual(suma(partes), 1); // el fixture realmente falla con ===
  assert.equal(validarReparto(partes).valido, true);
});

test("3. 1 + EPSILON es válida", () => {
  const partes = [0.5, 0.5 + Number.EPSILON];
  assert.notEqual(suma(partes), 1);
  assert.equal(validarReparto(partes).valido, true);
});

test("4. 50 % es inválida", () => {
  const r = validarReparto([0.25, 0.25]);
  assert.equal(r.valido, false);
  assert.match(r.mensaje ?? "", /debe sumar 1/);
});

test("5. 150 % es inválida", () => {
  assert.equal(validarReparto([0.75, 0.75]).valido, false);
});

test("6. 0.999 queda fuera de la tolerancia", () => {
  assert.ok(Math.abs(0.999 - 1) > TOLERANCIA);
  assert.equal(validarReparto([0.999]).valido, false);
});

test("7. null y undefined cuentan como 0", () => {
  assert.equal(validarReparto([0.5, null, 0.5, undefined]).valido, true);
});

test("8. sin datos es inválida", () => {
  const r = validarReparto([]);
  assert.equal(r.valido, false);
  assert.equal(r.suma, 0);
});

test("9. 11 miembros suman exactamente 10 000 puntos básicos", () => {
  const partes = repartirEnteros(Array<number>(11).fill(1));
  assert.equal(suma(partes), 10_000);
  assert.ok(partes.every((p) => p === 909 || p === 910));
  assert.equal(formatearPuntosBasicos(partes[0]), "9,10 %");
});

La prueba 6 es la más importante: una tolerancia mal elegida (por ejemplo 0.01) aceptaría sin avisar repartos que de verdad están incompletos.

Cómo verificar que quedó resuelto

node --test reparto.test.ts
npx tsc --noEmit

Node 24 ejecuta archivos .ts directamente quitando los tipos, por lo que no necesita un paso de compilación para las pruebas; el segundo comando valida los tipos. En la reproducción local las nueve pruebas pasaron, con 0 fallos, y tsc terminó con código de salida 0.

Para ganar confianza en el reparto entero, una comprobación aleatoria con unos 20 000 conjuntos de pesos (entre 1 y 40 miembros, algunos con peso 0) y repartos iguales de 1 a 300 miembros dio siempre una suma de 10 000, con enteros no negativos y cada parte a menos de una unidad de su cuota ideal.

Variantes y errores relacionados

La suma sale 0.01, 0.0001 o 100

No es coma flotante. Es una escala mal aplicada: dividir dos veces entre 100 (o ninguna) en alguna capa. Localiza la conversión duplicada en lugar de ampliar la tolerancia.

Importes de dinero

El mismo principio aplica: guarda la unidad mínima (centavos) como entero y convierte solo al mostrar.

Redondear con `toFixed` antes de comparar

Number(suma.toFixed(6)) === 1 funciona en la mayoría de los casos, pero pasa por una cadena y desplaza el problema al borde del redondeo. La comparación con tolerancia expresa mejor la intención.

`null`, `undefined` y `NaN`

En el validador, p ?? 0 trata null y undefined como 0. Un NaN contamina toda la suma, y Number.isFinite lo rechaza antes de comparar.

Cuando necesitas decimales exactos en muchos cálculos

Para repartos basta con enteros. Si tu dominio exige aritmética decimal exacta en operaciones encadenadas, evalúa una biblioteca de decimales en lugar de parchear cada comparación.

Resumen

Los Number de JavaScript son binarios de doble precisión: 0.1 no es exacto y === falla al comparar sumas con 1.
Valida con Math.abs(suma - 1) < 1e-6; Number.EPSILON es demasiado estricto para sumas acumuladas.
Elige una tolerancia mucho menor que la diferencia mínima real de tus datos, para que 0.999 siga siendo un error.
Reparte en enteros (puntos básicos) con el método del mayor resto para que el total sea exacto.
Define una sola escala y convierte una vez; una suma de 0.01 indica una división repetida, no un problema de precisión.

Referencias

WSL2 se cuelga por falta de memoria: ajusta .wslconfig

2026-11-01T15:00:00.000-05:00

Llevas un rato compilando proyectos Node.js dentro de WSL 2 con Docker Desktop abierto, y de pronto todo deja de funcionar a la vez:

Los comandos que pasan por wsl.exe pueden terminar con código de salida 1 y sin ninguna salida.
Docker pierde el socket y la CLI responde con un mensaje como este (el texto exacto varía según la versión):

Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?

Los servidores de desarrollo que estaban en marcha se cierran solos.

Cuando esto ocurre justo después de lanzar dos compilaciones o comprobaciones de tipos en paralelo (por ejemplo, dos next build), una causa frecuente es que se agotó la memoria de la máquina virtual de WSL 2. Este artículo explica cómo confirmarlo, cómo recuperar el entorno y cómo ajustar los límites en .wslconfig.

Por qué pasa

WSL 2 no usa directamente toda la RAM de Windows: ejecuta las distribuciones de Linux dentro de una máquina virtual ligera con un límite de memoria. Según la documentación de Microsoft, el valor por defecto de memory en el archivo .wslconfig es el 50 % de la memoria total de Windows, el espacio de intercambio (swap) por defecto es el 25 % del tamaño de esa memoria redondeado hacia arriba al GB más cercano, y processors usa todos los procesadores lógicos. Esa configuración se aplica a la máquina virtual que da soporte a todas las distribuciones WSL 2.

Docker Desktop con el backend de WSL 2 se ejecuta en una distribución propia (docker-desktop), pero dentro de esa misma máquina virtual, así que contenedores, compilaciones y servidores de desarrollo comparten la misma bolsa de memoria. Node.js no ayuda a contenerla: la opción --max-old-space-size (en MiB) fija el límite de la zona de memoria "old" del heap de V8 de cada proceso, no un límite global. Dos procesos con 6144 MiB de heap permitido suman 12 GiB solo en heap, más lo que consumen el sistema, Docker y los servidores de desarrollo.

Cuando la máquina virtual llega a su límite, los procesos pueden terminar de forma abrupta o dejar de responder, y todo lo que depende de ella (wsl.exe, el socket de Docker, los servidores) puede fallar al mismo tiempo. Es un diagnóstico por descarte, no un mensaje explícito, por eso conviene confirmarlo midiendo la memoria durante la tarea pesada.

Solución

Reinicia WSL desde Windows. Abre PowerShell (no un terminal de WSL) y ejecuta:
```
wsl --shutdown
```
Según la documentación, este comando termina de inmediato todas las distribuciones en ejecución y la máquina virtual ligera de WSL 2. Úsalo con cuidado: se cierran todos los procesos de todas tus distribuciones, así que guarda tu trabajo antes. Después, espera unos segundos (la documentación habla de unos 8 segundos) y comprueba que no queda nada activo:
```
wsl --list --running
```
Debe responder "There are no running distributions." (o el equivalente en tu idioma). Vuelve a abrir Docker Desktop, espera a que el motor aparezca como iniciado y abre un terminal nuevo.
Ejecuta las tareas pesadas de una en una. En lugar de lanzar dos compilaciones a la vez, encadénalas:
```
npm run typecheck && npm run build
```
Esto evita que dos heaps grandes coincidan en el tiempo.
Sube el límite de la máquina virtual en .wslconfig. El archivo no existe por defecto: debe estar en tu carpeta de usuario, %UserProfile%\.wslconfig. Puedes crearlo desde PowerShell con:
```
notepad $env:USERPROFILE\.wslconfig
```
Contenido de ejemplo (ajústalo a la RAM real de tu equipo):
```
[wsl2]
memory=12GB
swap=8GB
processors=6
```
Los tamaños admiten sufijos como GB o MB; sin sufijo se interpretan como bytes. No asignes toda la RAM: deja margen para Windows, o será Windows quien se quede sin memoria. Un valor de 12 GB solo tiene sentido en un equipo con bastante más RAM que eso (por ejemplo, 32 GB). Microsoft también recomienda modificar estas opciones desde la aplicación "WSL Settings" del menú Inicio en lugar de editar el archivo a mano.

Para aplicar los cambios, vuelve a ejecutar wsl --shutdown y espera a que WSL se detenga por completo. Si el archivo tiene errores de formato, la documentación indica que WSL arranca igualmente, pero sin aplicar la configuración.
Mantén el heap de Node.js dentro de la memoria de la máquina virtual. --max-old-space-size acepta MiB y se puede pasar mediante NODE_OPTIONS:
```
export NODE_OPTIONS=--max-old-space-size=4096
```
La documentación de Node.js recomienda dejar margen: en una máquina de 2 GiB sugiere 1536 MiB para dejar memoria al resto y evitar el uso de swap. Calcula el valor de modo que la suma de los heaps de los procesos que corren a la vez, más Docker y el sistema, quede por debajo de la memoria asignada.
Vigila el consumo mientras trabajas. Dentro de la distribución:
```
free -h
ps aux --sort=-%mem | head -n 8
docker stats --no-stream
```
free -h muestra la memoria total que ve la máquina virtual y cuánta queda libre; htop da una vista interactiva si lo tienes instalado.

Cómo verificar que quedó resuelto

Tras reiniciar, free -h dentro de WSL debe mostrar una memoria total cercana al valor de memory que configuraste (el sistema reserva una parte, así que no coincide exactamente). Si sigue mostrando el valor anterior, el archivo no se aplicó: revisa que se llame .wslconfig (sin extensión .txt), que esté en la carpeta de tu usuario y que tenga la sección [wsl2].
docker ps debe responder sin el error de conexión una vez que Docker Desktop indique que el motor está iniciado. Levanta de nuevo los contenedores que necesites.
Lanza la tarea pesada que provocó el problema, de una en una, y observa free -h. Si la memoria libre se acerca a cero y empieza a usarse swap de forma sostenida, sube el límite o reduce el heap de Node.js.

Variantes y errores relacionados

Devolver a Windows la memoria en caché

La documentación de Docker Desktop señala que, como WSL 2 asigna memoria de forma dinámica, Docker solo usa lo que necesita, y sugiere activar el ajuste experimental autoMemoryReclaim (en la sección [experimental] de .wslconfig) para que Windows recupere memoria retenida, como la caché de páginas que queda después de construir imágenes. Valores disponibles: disabled, gradual y dropCache. En la documentación actual de Microsoft, dropCache figura como valor por defecto, así que comprueba qué tienes configurado antes de tocarlo.

Detener solo una distribución

Si no quieres cerrar todo, wsl --terminate NombreDeLaDistribucion detiene solo la distribución indicada. La documentación describe wsl --shutdown como el comando que, además de terminar todas las distribuciones, apaga la máquina virtual ligera de WSL 2, que es lo que necesitas para aplicar cambios de .wslconfig o reiniciar el entorno.

El problema no es la memoria

Si wsl.exe falla y la memoria estaba holgada, revisa otras causas. Una documentada es un error al montar el disco de la distribución, que puede mostrar "An error occurred mounting the distribution disk, it was mounted read-only as a fallback." En ese caso, la documentación de Microsoft sobre espacio en disco describe cómo repararlo.

Si `wsl --shutdown` no basta

Como último recurso, reinicia Windows. Antes, guarda cualquier trabajo abierto fuera de WSL.

Resumen

WSL 2 corre en una máquina virtual con límite de memoria; por defecto, el 50 % de la RAM de Windows.
Dos compilaciones con heaps grandes, Docker y servidores de desarrollo pueden agotarla y dejar a wsl.exe y Docker sin respuesta.
Recupera el entorno con wsl --shutdown desde PowerShell y reabre Docker Desktop.
Ejecuta las tareas pesadas de una en una y ajusta memory, swap y processors en %UserProfile%\.wslconfig, aplicándolos con otro wsl --shutdown.
Mantén --max-old-space-size dentro de la memoria disponible y vigila el consumo con free -h.

Referencias

Git: Unable to create '.git/index.lock': File exists

2026-11-01T09:00:00.000-05:00

Ejecutas git add, git commit, git checkout o git merge y Git se detiene con este mensaje:

fatal: Unable to create 'C:/proyectos/mi-app/.git/index.lock': File exists.

Another git process seems to be running in this repository, or the lock file may be stale

En versiones anteriores de Git el texto es más largo, pero dice lo mismo:

fatal: Unable to create '/home/usuario/mi-app/.git/index.lock': File exists.

Another git process seems to be running in this repository, e.g.
an editor opened by 'git commit'. Please make sure all processes
are terminated then try again. If it still fails, a git process
may have crashed in this repository earlier:
remove the file manually to continue.

Este artículo explica qué es ese archivo, cómo distinguir un bloqueo huérfano de uno legítimo y cómo eliminarlo con seguridad en Windows, Linux o WSL.

Por qué pasa

Antes de modificar un archivo importante del repositorio, como el índice (el área de preparación o staging), Git crea junto a él un archivo con el mismo nombre y la extensión .lock. Según la documentación técnica de Git, el archivo de bloqueo se crea con la bandera O_CREAT|O_EXCL, es decir, la creación falla si ya existe. Git escribe en él el contenido nuevo y, al terminar, lo renombra al nombre original. Mientras tanto, quien solo lee sigue viendo el contenido anterior.

La documentación también explica que Git elimina sus archivos de bloqueo al salir, incluso cuando termina con un error o por una señal que puede capturar. Si ves el error, hay dos explicaciones posibles:

Otro proceso de Git está trabajando de verdad. Puede ser un IDE que consulta el estado en segundo plano, una interfaz gráfica de Git, un script o un comando tuyo en otra terminal. La documentación de git status advierte que, por defecto, escribe el índice refrescado y que ese bloqueo puede hacer fallar a otros procesos simultáneos. También un comando lento puede mantener el bloqueo: en una prueba con Git 2.54 para Windows, un git commit -a con un hook pre-commit de unos segundos mantuvo .git/index.lock mientras el hook corría, y un git add lanzado en ese lapso falló con este mismo error. Al terminar el hook, el archivo desapareció.
El bloqueo quedó huérfano. Si un proceso de Git se interrumpe de forma abrupta (cierre forzado, apagado del equipo, fallo del sistema), no llega a limpiar su archivo. El propio mensaje lo menciona: a git process may have crashed in this repository earlier.

Observa que no todos los comandos fallan: con un index.lock presente, git status siguió funcionando en la prueba, porque la escritura del índice que hace es opcional.

Solución

Identifica el archivo exacto. La ruta aparece en el mensaje. En un repositorio normal es .git/index.lock; en un worktree adicional (git worktree add) está en una carpeta propia dentro de .git/worktrees/. Para ver la ruta correcta desde cualquier carpeta del repositorio:
```
git rev-parse --git-path index.lock
```
Comprueba si hay realmente un proceso de Git en ejecución. En Linux, macOS o WSL:
```
pgrep -a git
```
En PowerShell:
```
Get-Process git -ErrorAction SilentlyContinue
```
(En el Administrador de tareas también puedes buscar git.exe.) Revisa además si tu editor o una herramienta gráfica de Git está haciendo una operación. Si hay un proceso activo, espera a que termine o ciérralo de forma normal, y vuelve a intentarlo. No borres el archivo mientras alguien lo está usando.
Si no hay ningún proceso de Git, borra el archivo. En Bash:
```
rm -f .git/index.lock
```
En PowerShell, desde la raíz del repositorio:
```
Remove-Item .git\index.lock
```
El archivo de bloqueo solo contiene la actualización a medio escribir, no tus datos: el índice original sigue intacto hasta que Git hace el renombrado final. Al borrar un bloqueo huérfano solo pierdes una actualización que nunca se completó.
Repite el comando que falló. Por ejemplo, git add ., git commit o git merge. Si el error vuelve a aparecer enseguida, hay un proceso que lo recrea: vuelve al paso 2 y revisa herramientas en segundo plano.

Cómo verificar que quedó resuelto

git status
git fsck --no-dangling
git log --oneline -3

git status debe mostrar el estado sin errores. git fsck verifica la conectividad y la validez de los objetos de la base de datos del repositorio; con --no-dangling omite la lista de objetos sin referencia. En la prueba no mostró salida y terminó con código de salida 0. git log confirma que HEAD apunta al último commit esperado. En PowerShell, Test-Path .git\index.lock debe devolver False.

En la reproducción local (un bloqueo vacío creado a mano, sin ningún proceso de Git activo), tras borrar el archivo el git add y el git commit pendientes se completaron y git fsck --no-dangling terminó con código 0.

Variantes y errores relacionados

Otros archivos de bloqueo: `HEAD.lock`, referencias y configuración

El mismo mecanismo protege otros archivos. Con un bloqueo presente, estos fueron los mensajes en la prueba:

fatal: cannot lock ref 'HEAD': Unable to create '.../.git/HEAD.lock': File exists.
fatal: cannot lock ref 'HEAD': Unable to create '.../.git/refs/heads/master.lock': File exists.
error: could not lock config file .git/config: File exists

La solución es la misma: confirma que no hay procesos de Git activos y borra únicamente el archivo .lock que menciona el mensaje.

Un mensaje con el número de proceso

En el código fuente más reciente de Git (rama principal), el mensaje puede incluir textos como Lock may be held by process seguido de un identificador de proceso. Si lo ves, comprueba ese identificador antes de borrar nada.

Herramientas que consultan el estado en segundo plano

Si tu editor o un script ejecuta git status continuamente, puede provocar este error en tus comandos. La documentación recomienda que los procesos en segundo plano usen:

git --no-optional-locks status

Es equivalente a definir la variable de entorno GIT_OPTIONAL_LOCKS=0: Git completa la operación sin las tareas opcionales que requieren un bloqueo, como refrescar el índice.

Hooks lentos

Si el bloqueo aparece siempre durante un git commit con hooks que ejecutan compilaciones o pruebas, el comando de Git es el que está en marcha: espera a que termine el hook antes de lanzar otro comando en ese repositorio.

Varios worktrees

Cada worktree tiene su propio index.lock. En la prueba, un index.lock en el repositorio principal no impidió un git add en un worktree adicional.

Resumen

index.lock es el archivo temporal con el que Git protege la actualización del índice; si ya existe, Git se niega a continuar.
Puede ser un proceso de Git legítimo (IDE, script, hook lento) o un bloqueo huérfano de un proceso interrumpido.
Comprueba primero los procesos (pgrep -a git o Get-Process git); si hay uno activo, espera.
Si no hay ninguno, borra solo ese archivo (rm -f .git/index.lock o Remove-Item .git\index.lock) y repite el comando.
Para herramientas en segundo plano, usa git --no-optional-locks status; verifica con git status y git fsck --no-dangling.

Referencias

Prisma update con undefined no borra el campo: usa null

2026-10-31T15:00:00.000-05:00

Editas un registro, borras el contenido de un campo opcional (o quitas una relación opcional), pulsas "Guardar" y la interfaz confirma que todo salió bien. Al recargar, el valor anterior sigue ahí. No hay ningún error en el servidor. Y si intentas enviar null para forzar el borrado, el esquema de validación lo rechaza:

Invalid input: expected number, received null

(En Zod 3 el texto es Expected number, received null.) Este artículo explica por qué Prisma ignora el cambio, cómo corregir el esquema de Zod para actualizaciones parciales (PATCH) y qué debe enviar el formulario para que "vaciar" un campo funcione.

Por qué pasa

La documentación de Prisma Client fija dos reglas: null is a value (null es un valor) y undefined means do nothing (undefined significa no hacer nada). En un update, una propiedad con undefined se trata como si no estuviera, y solo null escribe NULL en la base de datos. Con este modelo de ejemplo:

model Categoria {
  id        Int        @id @default(autoincrement())
  nombre    String
  productos Producto[]
}

model Producto {
  id          Int        @id @default(autoincrement())
  nombre      String
  descripcion String?
  categoriaId Int?
  categoria   Categoria? @relation(fields: [categoriaId], references: [id])
}

Partiendo de un producto con descripción y categoría, esto es lo que dejó cada llamada (Prisma 6.19, SQLite):

update({ data: { descripcion: undefined, categoriaId: undefined } })  // sin cambios
update({ data: { descripcion: null } })                                // descripcion = NULL
update({ data: { categoriaId: null } })                                // categoriaId = NULL

Ahora, ¿cómo llega undefined al update si el usuario solo vació el campo? Hay tres eslabones que fallan a la vez:

Una transformación de Zod convierte "" en undefined. Es un patrón muy común para "limpiar" formularios:
```
const textoOpcional = z.string().optional().transform((v) => v?.trim() || undefined);
// parse({ descripcion: '' })  ->  { descripcion: undefined }
```
Un campo vacío y un campo ausente quedan igual, y Prisma interpreta ambos como "no tocar".
El esquema de actualización no admite null. Con z.number().int().optional(), enviar null da el error de arriba. El formulario no tenía forma legal de pedir "ninguno".
El selector (combobox) no ofrecía "sin valor". Al quitar la selección enviaba undefined, y JSON.stringify descarta las propiedades con undefined:
```
JSON.stringify({ a: undefined, b: null })  // '{"b":null}'
```
La propiedad ni siquiera viaja en la petición.

Solución

En el esquema, convierte el texto vacío en null y admite null y ausencia.

import { z } from 'zod';

const textoLimpiable = z
  .string()
  .trim()
  .transform((v) => (v === '' ? null : v))
  .nullable()
  .optional();

export const actualizarProductoSchema = z.object({
  nombre: z.string().trim().min(1).optional(),   // obligatorio en BD: nunca null
  descripcion: textoLimpiable,                   // se puede vaciar
  categoriaId: z.number().int().positive().nullable().optional(),
});

Así se conservan los tres estados: clave ausente (no tocar), null (borrar) y valor (guardar). En la prueba, parse({}) devolvió {} sin ninguna clave, parse({ descripcion: '' }) y parse({ descripcion: ' ' }) devolvieron { descripcion: null }, y parse({ categoriaId: null }) devolvió { categoriaId: null }, tanto con Zod 4.6 como con Zod 3.25.

Pasa el resultado a Prisma tal cual. No "limpies" los null antes del update:
```
export function actualizarProducto(id: number, body: unknown) {
  const data = actualizarProductoSchema.parse(body);
  return prisma.producto.update({ where: { id }, data });
}
```
Las claves ausentes no se tocan y las que valen null se borran. Evita patrones como valor != null ? valor : undefined: la propia documentación de Prisma lo muestra como forma de ignorar un null, que es justo lo contrario de lo que necesitas aquí.

En la interfaz, envía null de forma explícita y ofrece una opción para quitar el valor:

<select
  value={form.categoriaId ?? ''}
  onChange={(e) =>
    setForm({ ...form, categoriaId: e.target.value === '' ? null : Number(e.target.value) })
  }
>
  <option value="">Quitar categoría</option>
  {categorias.map((c) => (
    <option key={c.id} value={c.id}>{c.nombre}</option>
  ))}
</select>

Para valores de texto basta con valor || null. Con identificadores numéricos usa la comparación con '' como arriba, porque 0 también es falso.

Para relaciones opcionales, elige un estilo y no los mezcles. Con la clave foránea escalar:
```
prisma.producto.update({ where: { id }, data: { categoriaId: null } });
```
O con la relación:
```
prisma.producto.update({ where: { id }, data: { categoria: { disconnect: true } } });
```
Ambas dejaron categoriaId en NULL en la prueba. La documentación indica que disconnect solo está disponible si la relación es opcional. Si pones categoriaId y categoria en el mismo data, Prisma lanza un PrismaClientValidationError con un mensaje como Unknown argument `categoriaId`. Did you mean `categoria`?.

Cómo verificar que quedó resuelto

Primero, prueba el esquema de forma aislada, sin base de datos:

expect(actualizarProductoSchema.parse({})).toEqual({});
expect('descripcion' in actualizarProductoSchema.parse({})).toBe(false);
expect(actualizarProductoSchema.parse({ descripcion: '' })).toEqual({ descripcion: null });
expect(actualizarProductoSchema.parse({ categoriaId: null })).toEqual({ categoriaId: null });

Después, comprueba el recorrido completo contra una base de datos de desarrollo: edita un registro, vacía la descripción y quita la categoría, guarda, recarga la página y consulta la fila (con Prisma Studio o una consulta SQL). Las dos columnas deben estar en NULL. En el recorrido de prueba con el cliente de Prisma, un PATCH con solo nombre dejó la descripción y la categoría intactas; uno con descripcion: '' dejó la descripción en NULL, y uno con categoriaId: null dejó la categoría en NULL.

Variantes y errores relacionados

Campos numéricos con `z.coerce.number()`

Un campo numérico vacío no se comporta como el texto: z.coerce.number().safeParse('') devolvió éxito con el valor 0. Vaciar el campo guardaría un cero. Convierte la cadena vacía antes:

const numeroLimpiable = z.preprocess(
  (v) => (v === '' ? null : v),
  z.coerce.number().nullable().optional(),
);

Campos obligatorios

No agregues .nullable() a las columnas que en la base de datos son obligatorias: el esquema debe rechazar el borrado antes de llegar a Prisma, con un error de validación claro.

Columnas `Json`

En campos Json, null es ambiguo (¿el valor JSON null o NULL de la base de datos?). Prisma ofrece Prisma.JsonNull y Prisma.DbNull para distinguirlos; revisa la documentación de campos JSON antes de usar null directamente.

Reutiliza la definición en creación y actualización

Si el esquema de creación y el de actualización definen el mismo campo de forma distinta (uno con .optional() y otro con .nullable().optional()), es fácil que vuelva a aparecer la diferencia entre vaciar y no tocar. Define los campos limpiables una sola vez (por ejemplo, textoLimpiable) y reutilízalos en ambos esquemas.

Resumen

En Prisma, undefined significa "no tocar el campo" y null significa "escribir NULL".
Una transformación como v?.trim() || undefined convierte "vaciar" en "no hacer nada" sin dar error.
Para campos limpiables usa .nullable().optional() y transforma "" en null; deja que las claves ausentes sigan ausentes.
El formulario debe enviar null de forma explícita (JSON.stringify elimina undefined) y ofrecer una opción "Quitar".
Para relaciones opcionales usa categoriaId: null o categoria: { disconnect: true }, nunca ambos en la misma operación.

Referencias

Flexbox: la tabla ancha rompe el layout (falta min-w-0)

2026-10-31T09:00:00.000-05:00

Tienes un panel con barra lateral y un contenido principal, todo con Flexbox. Pones dentro una tabla ancha y, en lugar de aparecer una barra de desplazamiento horizontal en la tabla, ocurre esto:

Toda la página se ensancha y aparece un scroll horizontal en el navegador, no en la tabla.
Aparece además un segundo scroll vertical fuera del contenido: al bajar se mueven la barra lateral y la cabecera, y debajo queda una zona en blanco.
En un modal con altura limitada, las filas de una lista se aplastan hasta quedar de unos pocos píxeles.

Esta es una estructura típica que produce el problema:

<div class="flex h-screen">
  <aside class="hidden w-56 shrink-0 bg-slate-900 p-4 text-white md:block">Menú</aside>
  <div class="flex flex-1 flex-col">
    <header class="h-14 shrink-0 border-b px-4">Cabecera</header>
    <main class="flex-1 p-4">
      <div class="overflow-y-auto">
        <div class="overflow-x-auto">
          <table class="w-[2600px] table-fixed text-sm">...</table>
        </div>
      </div>
    </main>
  </div>
</div>

Al medirla en el navegador con una ventana de 1366 × 768 px, estos fueron los valores:

columna de contenido:   2632 px de ancho   (la tabla mide 2600 px)
página:                 scrollWidth 2856, clientWidth 1351
contenedor de la tabla: scrollWidth 2600 = clientWidth 2600  -> nunca hay barra

Los tres síntomas tienen una raíz común en cómo Flexbox calcula el tamaño mínimo de sus elementos.

Por qué pasa

Los elementos hijos de un contenedor flex tienen por defecto min-width: auto y min-height: auto. Según MDN, para un elemento flex ese mínimo automático es el tamaño mínimo de su contenido (min-content), salvo que el elemento sea un contenedor de scroll: en ese caso el mínimo automático es 0. La especificación (CSS Flexible Box Layout, sección "Automatic Minimum Size of Flex Items") lo expresa igual: el mínimo automático es el tamaño mínimo basado en el contenido y, para los contenedores de scroll, cero.

Esto explica los tres síntomas:

La tabla ensancha todo. La columna de contenido (flex-1) no es un contenedor de scroll, así que no puede ser más estrecha que el contenido más ancho que lleve dentro: la tabla de 2600 px. El contenedor con overflow-x: auto que envuelve la tabla recibe un ancho de 2600 px, no desborda y por eso no muestra barra. Es la columna la que desborda a la página.
El segundo scroll vertical. Si el <main> es un elemento flex en columna y el scroll lo tiene un elemento interior (o ninguno), su altura mínima automática es la del contenido: <main> crece y empuja todo. Con un contenedor de altura 100vh, el desbordamiento lo gestiona la página, y la barra lateral (que mide lo mismo que el contenedor) se desplaza con ella.
Las filas aplastadas. flex-shrink vale 1 por defecto (MDN), así que los elementos se encogen para no desbordar el contenedor. Normalmente min-height: auto impide que bajen del tamaño de su contenido, pero una fila con overflow: hidden (por ejemplo, para recortar texto con truncate) es un contenedor de scroll, su mínimo automático es 0 y se encoge hasta quedarse en su relleno (padding). Con py-2 eso son 16 px.

Solución

Estructura del layout con Tailwind. Este es el esqueleto completo (puedes ponerlo en el layout.tsx de tu panel en Next.js):
```
<div class="flex h-dvh overflow-hidden">
  <aside class="hidden w-56 shrink-0 bg-slate-900 p-4 text-white md:block">Menú</aside>

  <div class="flex min-w-0 flex-1 flex-col">
    <header class="h-14 shrink-0 border-b px-4">Cabecera</header>

    <main class="min-h-0 flex-1 overflow-y-auto p-4">
      <div class="overflow-x-auto">
        <table class="w-[2600px] table-fixed text-sm">
          
        </table>
      </div>
    </main>
  </div>
</div>
```
- h-dvh overflow-hidden en el contenedor raíz: la página ocupa exactamente la ventana y nunca tiene scroll propio. h-dvh equivale a height: 100dvh (Tailwind lo documenta como la altura del viewport que cambia cuando se expande o se contrae la interfaz del navegador); si tu versión no lo incluye, usa h-screen.
- min-w-0 en el hijo flex que contiene la tabla: devuelve el mínimo a 0 y deja que la columna se ajuste al espacio disponible.
- min-h-0 flex-1 overflow-y-auto en <main>: es el único elemento con scroll vertical.
- overflow-x-auto en el contenedor directo de la tabla: es el único elemento con scroll horizontal. Un contenedor de scroll por eje y por tabla; no repitas overflow en los ancestros.
- shrink-0 en la barra lateral y la cabecera, para que no se encojan.

El mismo layout en CSS puro:

.shell   { display: flex; height: 100dvh; overflow: hidden; }
.sidebar { width: 14rem; flex-shrink: 0; }
.content { display: flex; flex-direction: column; flex: 1; min-width: 0; }
.header  { flex-shrink: 0; height: 3.5rem; }
.main    { flex: 1; min-height: 0; overflow-y: auto; padding: 1rem; }
.table-scroll { overflow-x: auto; }
.table-scroll table { width: 2600px; }

En Tailwind 4.3, min-w-0 genera min-width: 0, min-h-0 genera min-height: 0, shrink-0 genera flex-shrink: 0 y h-dvh genera height: 100dvh.

Listas con scroll dentro de un modal o un panel de altura limitada: evita que las filas se encojan.

<div class="flex max-h-72 w-80 flex-col rounded border bg-white">
  <div class="shrink-0 border-b p-3">Buscar</div>
  <ul class="flex flex-col overflow-y-auto">
    <li class="shrink-0 overflow-hidden px-3 py-2">Resultado 1</li>
    <!-- más filas -->
  </ul>
</div>

En CSS: li { flex-shrink: 0; }. Así la lista conserva la altura de cada fila y desborda, y el scroll aparece en el <ul>.

Cómo verificar que quedó resuelto

En la consola del navegador, con la vista que falla abierta:

const s = document.scrollingElement;
({ paginaScrollX: s.scrollWidth > s.clientWidth, paginaScrollY: s.scrollHeight > s.clientHeight })

Ambos valores deben ser false. Después comprueba que el único scroll vertical está en <main> (main.scrollHeight > main.clientHeight) y que el contenedor de la tabla desborda por dentro (wrapper.scrollWidth > wrapper.clientWidth). Repite con el ancho de un móvil.

En la prueba, con ventanas de 1366 × 768 y de 375 × 812 px (Chromium), la versión que falla tenía scroll de página en ambos ejes y la columna medía 2632 px. Con el arreglo, la página no tenía scroll en ningún eje, <main> era el único con scroll vertical y la tabla de 2600 px se desplazaba dentro de su contenedor (1095 px visibles en escritorio, 328 px en móvil). En el modal, las filas pasaron de 16 px a su altura natural (entre 40 y 64 px, según si el texto ocupaba una o dos líneas).

Variantes y errores relacionados

`overflow-hidden` en el contenedor raíz sin `min-w-0`

Si pones overflow-hidden en el contenedor raíz pero olvidas min-w-0, el scroll de página desaparece y el problema queda oculto: en la prueba la columna seguía midiendo 2647 px, el contenedor de la tabla no mostraba barra y la tabla quedaba recortada por la ventana. Si ves una tabla cortada sin forma de desplazarla, revisa min-w-0.

¿Hace falta `min-h-0` si ya hay `overflow-y-auto`?

Si <main> es el propio contenedor de scroll, no: su mínimo automático ya es 0 (en la prueba funcionó igual sin min-h-0). Sí hace falta cuando el scroll lo tiene un elemento interior, por ejemplo un <div class="h-full overflow-y-auto"> dentro de <main>: sin min-h-0, <main> creció hasta el alto de su contenido (2304 px); con min-h-0 se quedó en el espacio disponible. Dejar ambas clases es inocuo y evita depender de ese detalle.

Lo mismo en CSS Grid

MDN indica que el mínimo automático también afecta a los elementos de una rejilla. En la prueba, con grid-template-columns: 14rem 1fr la columna medía 2600 px y la página desbordaba; con 14rem minmax(0, 1fr) la columna medía 1142 px y la tabla se desplazaba dentro de su contenedor. En Tailwind: grid-cols-[14rem_minmax(0,1fr)].

Texto largo sin espacios en un elemento flex

Una URL o un identificador largo sin espacios puede ensanchar un elemento flex por el mismo motivo. En la prueba, con solo overflow-wrap: break-word (clase break-words en Tailwind) la columna siguió desbordando la página en un ancho de 375 px; al añadir min-w-0 a ese elemento el texto se partió y la página dejó de desbordar. Si prefieres cortar el texto con puntos suspensivos, usa truncate junto con min-w-0.

Resumen

Los elementos flex no se encogen por debajo del tamaño de su contenido (min-width: auto y min-height: auto), salvo que sean contenedores de scroll.
Una tabla ancha estira la columna de contenido; pon min-w-0 en el hijo flex que la contiene y overflow-x-auto en su envoltorio directo.
Evita el segundo scroll vertical con un contenedor raíz h-dvh overflow-hidden y min-h-0 flex-1 overflow-y-auto en <main>.
Las filas de una lista con scroll necesitan shrink-0 para no aplastarse cuando el contenedor tiene altura limitada.
Verifica con scrollWidth y clientWidth de la página: ambos ejes sin scroll de página y un solo contenedor de scroll por eje.

Referencias

Tests pasan en local y fallan en CI: variables y CRLF

2026-10-30T15:00:00.000-05:00

Ejecutas la suite en tu equipo y todo está en verde. Subes el cambio, el flujo de CI se pone en rojo y el error no apunta a ninguna línea que hayas tocado:

 FAIL  src/pagos/route.test.ts > POST /api/pagos > crea un pago
AssertionError: expected 503 to be 201 // Object.is equality

 FAIL  src/importar.test.ts > fixture ventas.csv > tiene encabezado y 7 filas
AssertionError: expected [ Array(1) ] to have a length of 8 but got 1

Este artículo explica dos causas muy comunes de "pasa en local, falla en CI" en proyectos Node.js con Vitest o Jest: variables de entorno leídas en el momento de importar un módulo y saltos de línea distintos entre Windows y Linux. Incluye cómo reproducir el fallo de CI en tu propia máquina antes de subir nada.

Por qué pasa

Causa 1: `process.env` se lee una sola vez, al importar

Mira este manejador de ruta (por ejemplo, un route handler de Next.js o cualquier módulo de Node.js):

// src/pagos/route.ts
const PAYMENT_KEY = process.env.PAYMENT_KEY; // se evalúa UNA vez, al importar el módulo

export async function POST(request: Request): Promise<Response> {
  if (!PAYMENT_KEY) {
    return Response.json({ error: 'Pagos no configurados' }, { status: 503 });
  }
  // ...
}

Un módulo ES se evalúa la primera vez que alguien lo importa, y los import estáticos de un archivo de test se resuelven antes de que se ejecute el cuerpo de ese archivo. Por eso este intento de controlar la variable no sirve:

import { beforeEach, describe, expect, it, vi } from 'vitest';
import { POST } from './route'; // aquí se lee PAYMENT_KEY

beforeEach(() => {
  vi.stubEnv('PAYMENT_KEY', 'clave-de-prueba'); // llega tarde: la constante ya se fijó
});

La constante quedó con el valor que tenía el proceso al arrancar. En tu equipo esa variable existe, porque la define tu terminal o un archivo .env que carga tu configuración de pruebas. En CI no existe, y el manejador responde 503 en todos los tests que esperaban un pago correcto.

La documentación de Vitest indica que, por defecto, solo carga automáticamente desde los archivos .env las variables con prefijo VITE_. Lo comprobé con Vitest 5.0.3: una variable PAYMENT_KEY escrita en .env no aparecía en process.env dentro de los tests, y una VITE_... sí. Si en tu proyecto la variable llega a los tests, es porque algo más la carga (tu shell, un setup con dotenv, loadEnvConfig de @next/env o la opción test.env), y ese "algo" no existe igual en CI.

El problema también funciona al revés: un test como "responde 503 si falta la clave" pasa en CI y falla en tu equipo, porque ahí la clave sí está definida. Depender del .env de cada máquina hace que el resultado dependa de quién ejecute los tests.

Causa 2: el test solo entiende `\r\n`

Un test lee un CSV de ejemplo y lo parte en líneas con split('\r\n'). El repositorio guarda el archivo con \n. En Windows es habitual que core.autocrlf esté en true (compruébalo con git config --show-origin --get core.autocrlf), y entonces Git convierte los saltos de línea al hacer checkout: el archivo llega con \r\n y el test pasa. En el runner de Linux no hay conversión, el archivo conserva \n, el split no encuentra nada que cortar y devuelve un solo elemento con todo el contenido. Según cómo esté escrita la aserción, el test falla (como arriba) o, peor, pasa sin comprobar nada:

const rows = raw.split('\r\n').filter(Boolean).slice(1); // en Linux: []
rows.forEach((row) => {
  expect(row.split(',')).toHaveLength(3); // nunca se ejecuta
});

Un bucle sobre una lista vacía no ejecuta ninguna aserción, y el test queda en verde.

Solución

Reproduce CI en local. Ejecuta la suite sin las variables que solo existen en tu equipo. En Git Bash o Linux:
```
env -u PAYMENT_KEY npx vitest run
```
En PowerShell (afecta solo a la sesión actual):
```
Remove-Item Env:PAYMENT_KEY -ErrorAction SilentlyContinue
npx vitest run
```
Si tu configuración carga un .env, renómbralo temporalmente. Con este paso se reproduce el 503 sin esperar al pipeline.

Lee la variable cuando la necesites, no al importar.

const getPaymentKey = () => process.env.PAYMENT_KEY;

export async function POST(request: Request): Promise<Response> {
  if (!getPaymentKey()) {
    return Response.json({ error: 'Pagos no configurados' }, { status: 503 });
  }
  // ...
}

Otra opción es recibir la configuración por parámetro (inyección de dependencias) y leer process.env solo en un punto de entrada.

Define las variables dentro del test, no en el entorno de cada máquina. vi.stubEnv cambia el valor en process.env y en import.meta.env; vi.unstubAllEnvs() restaura los valores originales:

import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
import { POST } from './route';

afterEach(() => {
  vi.unstubAllEnvs();
});

describe('POST /api/pagos', () => {
  beforeEach(() => {
    vi.stubEnv('PAYMENT_KEY', 'clave-de-prueba');
  });

  it('crea un pago', async () => {
    const res = await POST(new Request('http://localhost/api/pagos', {
      method: 'POST',
      body: JSON.stringify({ monto: 10 }),
    }));
    expect(res.status).toBe(201);
  });
});

describe('sin clave configurada', () => {
  it('responde 503', async () => {
    vi.stubEnv('PAYMENT_KEY', undefined); // el valor puede ser undefined
    // ...
  });
});

Si prefieres no escribir el afterEach en cada archivo, Vitest tiene la opción unstubEnvs: true en test, que llama a vi.unstubAllEnvs() antes de cada test (por defecto está en false).

Si no puedes cambiar el módulo, reinicia el registro de módulos y vuelve a importarlo después de fijar la variable:
```
let POST: (request: Request) => Promise<Response>;

beforeEach(async () => {
  vi.resetModules();
  vi.stubEnv('PAYMENT_KEY', 'clave-de-prueba');
  ({ POST } = await import('./route')); // se evalúa de nuevo, ya con la variable
});
```
La documentación aclara que los imports de nivel superior no se pueden reevaluar, por eso hace falta el import() dinámico. En Jest el equivalente es jest.resetModules() (o jest.isolateModules) más una asignación a process.env.

Parte las líneas aceptando ambos separadores y exige que el test compruebe algo:

const lines = raw.split(/\r?\n/).filter(Boolean);

it('todas las filas tienen 3 columnas', () => {
  expect.hasAssertions(); // falla si no se ejecutó ninguna aserción
  lines.slice(1).forEach((row) => {
    expect(row.split(',')).toHaveLength(3);
  });
});

Fija los saltos de línea de los fixtures con un archivo .gitattributes en la raíz del repositorio:
```
*.csv text eol=lf
```
Con eol=lf, el archivo se queda con \n en el directorio de trabajo, sea cual sea core.autocrlf. Para corregir los archivos que ya estaban guardados con otro formato, ejecuta git add --renormalize . y revisa el resultado con git status antes de confirmar.

Cómo verificar que quedó resuelto

Ejecuta la suite en las cuatro combinaciones posibles: con y sin la variable, y con el fixture en LF y en CRLF.

PAYMENT_KEY=valor-local npx vitest run
env -u PAYMENT_KEY npx vitest run

Repite ambos comandos después de convertir el fixture de formato (por ejemplo, con un editor que permita elegir LF o CRLF para el archivo). En un proyecto de ejemplo con 10 tests, las cuatro ejecuciones terminaron con "10 passed". Antes del arreglo, la ejecución sin variable fallaba en 6 de 8 tests, y con el fixture en LF el test del split('\r\n') fallaba y otro pasaba sin ninguna aserción.

Variantes y errores relacionados

La variable sí es necesaria en CI

Si un test de integración necesita un secreto real, defínelo en el flujo de trabajo con env: a partir de secrets. Ten en cuenta que, según la documentación de GitHub, los secretos no se pasan al runner cuando el flujo lo dispara un fork; ahí la variable no estará disponible. Para tests unitarios, usa valores de prueba en lugar de secretos.

Next.js y los archivos `.env`

La documentación de Next.js indica que en el entorno test no se carga .env.local, para que los resultados no dependan de cada persona. Puedes versionar un .env.test con valores falsos y cargarlo con loadEnvConfig de @next/env en tu configuración de pruebas.

El cache de módulos entre tests

Si usas vi.resetModules() y el módulo mantiene estado (conexiones, singletons), cada import() crea una instancia nueva. Es lo que buscas aquí, pero recuérdalo si compartes instancias entre tests.

Un fixture ya confirmado con CRLF

Cambiar .gitattributes no reescribe por sí solo lo que está en el repositorio. Por eso existe git add --renormalize: aplica de nuevo el filtro de normalización a todos los archivos versionados.

Resumen

Una constante de módulo que lee process.env se fija al importar; vi.stubEnv en beforeEach llega tarde.
Lee la variable dentro de una función o inyecta la configuración, y en los tests usa vi.stubEnv con vi.unstubAllEnvs().
Reproduce CI ejecutando la suite sin las variables de tu equipo (env -u VARIABLE o Remove-Item Env:VARIABLE).
Parte líneas con /\r?\n/, usa expect.hasAssertions() y fija los fixtures con *.csv text eol=lf.
Prueba siempre las combinaciones con y sin variable, y con LF y CRLF.

Referencias

Postgres: AT TIME ZONE no convierte un timestamp sin zona

2026-10-30T09:00:00.000-05:00

Guardas fechas en UTC en columnas timestamp without time zone (es lo que genera Prisma por defecto) y quieres mostrarlas en la hora local de usuarios que están en UTC-5. Aplicas AT TIME ZONE y el resultado parece incorrecto: con la sesión en UTC, el valor guardado 2026-10-11 15:00:00 sale como una hora posterior, y con la sesión en la zona local sale idéntico, como si no hubiera convertido nada:

SELECT creado_en AT TIME ZONE 'America/Bogota' FROM pedidos;

-- sesión en UTC:
2026-10-11 20:00:00+00
-- sesión en America/Bogota:
2026-10-11 15:00:00-05

La hora local correcta sería 10:00. Un problema emparentado: las filas que insertó una migración con now() aparecen 5 horas desfasadas en la aplicación, y los cálculos por días (ventanas de vigencia, informes por fecha) cambian de día cerca de la medianoche. Todo tiene el mismo origen.

Por qué pasa

La documentación de PostgreSQL (funciones de fecha y hora) define dos comportamientos distintos para AT TIME ZONE, según el tipo del valor:

timestamp without time zone AT TIME ZONE zona devuelve un timestamp with time zone y supone que el valor ya está expresado en esa zona.
timestamp with time zone AT TIME ZONE zona devuelve un timestamp without time zone: la hora que marcaría un reloj en esa zona.

Con una columna sin zona, AT TIME ZONE 'America/Bogota' no convierte desde UTC: declara que 15:00 ya es hora de Bogotá, lo que equivale a 20:00 UTC. El resultado es un timestamptz, y psql lo muestra con la zona de la sesión (TimeZone): 20:00+00 en una sesión UTC y 15:00-05 en una sesión de Bogotá. Es la dirección contraria a la que mucha gente espera.

El desfase de now() tiene la misma raíz. now() devuelve un timestamptz, y al guardarlo en una columna sin zona PostgreSQL aplica la regla general: las conversiones entre ambos tipos suponen que el valor sin zona está en la hora local de TimeZone. Si la migración corre con la sesión en America/Bogota, se guarda la hora de pared local. Una aplicación que interprete esa columna como UTC la lee 5 horas antes. PostgreSQL no guarda ninguna zona en esa columna, así que la convención es de la aplicación; Prisma, cuyo tipo DateTime se mapea por defecto a timestamp(3), suele tratar esos valores como UTC, aunque su documentación no lo garantiza de forma explícita.

Cerca de medianoche el desfase cambia el día: las 20:30 del día 11 en Bogotá son las 01:30 UTC del día 12. En la prueba, ese instante convertido a timestamp con la sesión en hora local se guardó como 2026-10-11 20:30:00 (fecha 11), mientras que en UTC es 2026-10-12 01:30:00 (fecha 12). Cualquier cálculo por días o por fecha sale distinto según qué valor se use.

Solución

Para mostrar en hora local un valor guardado en UTC, usa dos veces AT TIME ZONE. La primera declara que el valor está en UTC (obtienes un timestamptz) y la segunda lo expresa en la zona deseada (obtienes un timestamp sin zona, que no depende de la sesión):
```
SELECT creado_en AT TIME ZONE 'UTC' AT TIME ZONE 'America/Bogota' AS hora_local
FROM pedidos;

-- equivalente con la función timezone()
SELECT timezone('America/Bogota', timezone('UTC', creado_en)) AS hora_local
FROM pedidos;
```
Con el ejemplo anterior devuelve 2026-10-11 10:00:00, tanto con la sesión en UTC como en America/Bogota.

Al guardar, convierte now() a UTC de forma explícita si la columna es timestamp without time zone:

INSERT INTO sesiones (creado_en) VALUES (timezone('UTC', now()));
-- o, con la misma semántica:
INSERT INTO sesiones (creado_en) VALUES (now() AT TIME ZONE 'UTC');

-- valor por defecto de la columna
ALTER TABLE sesiones ALTER COLUMN creado_en SET DEFAULT timezone('UTC', now());

Aplícalo también en las migraciones y scripts manuales que escriban estas columnas: no usan el código de tu aplicación.

En columnas nuevas, prefiere timestamptz. PostgreSQL guarda el instante normalizado a UTC y lo convierte a la zona de la sesión al mostrarlo, así que no hay una convención implícita que se pueda romper. En Prisma se declara con el atributo nativo @db.Timestamptz(3):
```
model Pedido {
  id        Int      @id @default(autoincrement())
  creadoEn  DateTime @default(now()) @db.Timestamptz(3)
}
```
Para convertir una columna existente, indica siempre cómo interpretar los valores antiguos:
```
ALTER TABLE pedidos
  ALTER COLUMN creado_en TYPE timestamptz
  USING creado_en AT TIME ZONE 'UTC';
```
Sin la cláusula USING, PostgreSQL aplica la conversión implícita con la zona de la sesión. En la prueba, con la sesión en America/Bogota, el valor 15:00 se convirtió en 20:00+00; con USING ... AT TIME ZONE 'UTC' quedó en 15:00+00. Este cambio de tipo puede reescribir la tabla, así que planifícalo en tablas grandes.
Fija la zona de la sesión de forma consciente. Consulta el valor actual con SHOW TimeZone; y cámbialo para la sesión con SET TimeZone = 'UTC';. Para que cada sesión nueva de un rol arranque en UTC:
```
ALTER ROLE mi_usuario SET timezone = 'UTC';
```
La documentación indica que el valor se aplica al iniciar sesión el rol y reemplaza al de postgresql.conf. En la prueba, SHOW timezone pasó de America/Bogota a UTC en la conexión siguiente.

Cómo verificar que quedó resuelto

Esta comprobación crea una tabla de prueba y deja la sesión en la zona local, que es el caso que provoca el desfase:

CREATE TABLE prueba_zona (id serial PRIMARY KEY, creado_en timestamp NOT NULL);
SET TimeZone = 'America/Bogota';
INSERT INTO prueba_zona (creado_en) VALUES (now()), (timezone('UTC', now()));

SELECT id,
       round(extract(epoch FROM ((creado_en AT TIME ZONE 'UTC') - now())) / 3600, 2) AS desfase_horas
FROM prueba_zona
ORDER BY id;

DROP TABLE prueba_zona;

La fila 1 (now() sin convertir) debe mostrar un desfase de -5.00 horas, y la fila 2 (timezone('UTC', now())) debe mostrar 0.00. Si tu aplicación calcula una caducidad, comprueba también que el tiempo restante justo después de crear el registro sea exactamente el esperado, sin horas de más ni de menos.

Variantes y errores relacionados

Valores con desplazamiento escritos como `timestamp`

Según la documentación, cuando un valor se interpreta como timestamp without time zone, PostgreSQL ignora en silencio cualquier indicación de zona de la entrada. Por eso '2026-10-11 15:00:00-05'::timestamp queda como 15:00, sin ajuste. Para conservar el instante, escribe el tipo completo: TIMESTAMP WITH TIME ZONE '2026-10-11 15:00:00-05'.

Obtener la fecha local, no la de UTC

Para agrupar por día local usa la zona de forma explícita: (now() AT TIME ZONE 'America/Bogota')::date. Si la columna es un timestamp guardado en UTC, convierte primero con la doble conversión de la solución 1 y después aplica ::date.

Prisma, `timestamptz` y adaptadores de controlador

Al escribir este artículo había una incidencia abierta en el repositorio de Prisma (prisma/orm, número 26786) que describe lecturas desplazadas con @db.Timestamptz al usar adaptadores de controlador cuando la zona horaria de PostgreSQL no es UTC. Revisa su estado y prueba con tu versión antes de migrar columnas.

`timezone(zona, valor)` equivale a `AT TIME ZONE`

La documentación indica que la función timezone(zona, valor) es equivalente a la construcción valor AT TIME ZONE zona. Fíjate en el orden de los argumentos: la zona va primero.

Resumen

En un timestamp without time zone, AT TIME ZONE 'X' supone que el valor ya está en la zona X y devuelve un timestamptz; no convierte desde UTC.
Para pasar de UTC a hora local: col AT TIME ZONE 'UTC' AT TIME ZONE 'America/Bogota'.
now() es timestamptz; al guardarlo en una columna sin zona se usa la zona de la sesión. Usa timezone('UTC', now()) o now() AT TIME ZONE 'UTC'.
Prefiere timestamptz en columnas nuevas y migra las antiguas con USING col AT TIME ZONE 'UTC'.
Revisa SHOW TimeZone en cada entorno que ejecute migraciones o scripts.

Referencias

git push | tail devuelve código 0 aunque el push falle

2026-10-29T15:00:00.000-05:00

Ejecutas el push recortando la salida para no llenar la pantalla, o lo lanzas desde una herramienta que solo informa del código de salida del comando completo:

git push origin main 2>&1 | tail -20

El resultado dice que el comando terminó con código 0 y das el trabajo por subido. Sin embargo, al revisar el servidor el remoto sigue con el commit anterior, y las últimas líneas que viste no explican el motivo:

$ git push origin main 2>&1 | tail -3
build: paso 39 de 40
build: paso 40 de 40
error: failed to push some refs to 'https://example.com/equipo/mi-app.git'
$ echo $?
0

Este artículo explica por qué una tubería (pipe) oculta el fallo de git push, cómo obtener el código de salida real y cómo comprobar que el remoto recibió tu commit.

Por qué pasa

El manual de Bash define el estado de salida de una tubería como el del último comando, salvo que la opción pipefail esté activa. En git push ... | tail el último comando es tail, que termina bien siempre que pueda imprimir algo. El código de git push se descarta sin avisar.

Además, la causa del fallo suele estar en otro lugar. Git ejecuta el hook pre-push antes de enviar nada y, según su documentación, si ese hook termina con un estado distinto de cero el push se aborta sin enviar nada. Cuando el hook ejecuta lint, comprobación de tipos o un build, puede fallar por motivos del entorno (un permiso denegado sobre un archivo bloqueado, falta de memoria). Su mensaje aparece al principio de la salida, justo la parte que tail -20 recorta.

En la prueba, con un hook que terminaba con error, git push devolvió 1, la tubería completa devolvió 0 y el remoto conservó el hash anterior. También se ve el segundo efecto: con tail -3 desapareció la línea con el motivo (un EPERM simulado) que el hook había impreso al inicio.

Solución

No pases git push por una tubería. Redirige la salida completa a un archivo y lee el código justo después:
```
git push origin main > push.log 2>&1
echo "git push terminó con código $?"
tail -n 20 push.log
```
El echo va antes que tail porque $? guarda solo el estado del último comando ejecutado. El archivo conserva todo el mensaje, de modo que puedes buscar el motivo con grep -n -i error push.log.
Si necesitas la tubería, activa pipefail. Con esta opción, el estado de la tubería pasa a ser el del último comando (el de más a la derecha) que terminó con un valor distinto de cero:
```
set -o pipefail
git push origin main 2>&1 | tail -n 20
echo "código: $?"
```
En la prueba imprimió código: 1. En un script, coloca set -o pipefail al principio; en una sesión interactiva afecta a todos los comandos siguientes.
O consulta PIPESTATUS (variable de Bash). Es un arreglo con el estado de cada comando de la última tubería ejecutada en primer plano:
```
git push origin main 2>&1 | tail -n 20
echo "git push: ${PIPESTATUS[0]}  tail: ${PIPESTATUS[1]}"
```
La salida de la prueba fue git push: 1 tail: 0. Debes leerla en el comando inmediatamente posterior a la tubería, porque cualquier otro comando la sobrescribe.
Comprueba el remoto, no solo el código. git ls-remote muestra los hashes que tiene el servidor; el primero debe coincidir con el de tu HEAD:
```
git ls-remote origin refs/heads/main
git rev-parse HEAD
```
Otra opción es actualizar la información remota y mirar el estado resumido:
```
git fetch origin
git status -sb
```
Si la primera línea muestra ## main...origin/main [ahead 1], tienes un commit que el remoto no recibió.
Corrige la causa real y repite el push sin tubería. Busca en push.log la primera línea de error y ejecuta a mano los comandos del hook (lint, tipos, build) para reproducirlo. Evita usar git push --no-verify solo para que el push pase: según la documentación de Git, esa opción omite el hook por completo, y los errores que detectaba llegarán al remoto.

Cómo verificar que quedó resuelto

git push origin main > push.log 2>&1; echo "código: $?"
git ls-remote origin refs/heads/main
git rev-parse HEAD
git status -sb

El código debe ser 0, el hash de ls-remote debe ser idéntico al de rev-parse y la primera línea de git status -sb no debe incluir [ahead ...]. En la prueba, antes de corregir la causa el hash remoto era distinto del local y el estado mostraba [ahead 1]; después de eliminar la causa del fallo del hook y empujar sin tubería, el código fue 0, ambos hashes coincidieron y el estado volvió a ## main...origin/main.

Variantes y errores relacionados

PowerShell: usa `$LASTEXITCODE`

git push origin main 2>&1 | Select-Object -Last 20
$LASTEXITCODE

En Windows PowerShell 5.1, tras esa tubería $LASTEXITCODE conservó el código de git (1), pero $? valía True porque el último comando de la tubería terminó bien. Para decidir si el push funcionó, usa $LASTEXITCODE y no $?.

Cualquier comando seguido de una tubería

El mismo problema afecta a npm run build | tail, docker build . | tail o pytest | tee resultado.log. Si el comando de la izquierda falla y el de la derecha no, el resultado visible es éxito. Aplica set -o pipefail o redirige a un archivo.

`&&` e `if` también se engañan

git push origin main 2>&1 | tail -n 20 && echo "subido"

Sin pipefail, este comando imprime subido aunque el push haya fallado; con pipefail activo, no lo imprime.

`set -e` no basta

En un script con set -e, un comando que falla en mitad de una tubería no detiene la ejecución, porque el estado que cuenta es el del último. En la prueba, false | cat no interrumpió el script con set -e y sí lo hizo con set -eo pipefail. Para scripts de despliegue o de CI, la combinación habitual es esta última.

"Everything up-to-date" también devuelve 0

Un push sin cambios nuevos termina con código 0 de forma legítima. Por eso conviene comparar siempre los hashes con git ls-remote y git rev-parse HEAD: te dicen si el remoto tiene tu commit, sin depender del texto ni del código.

Resumen

El código de salida de git push ... | tail es el de tail, no el de git push; un hook pre-push fallido queda oculto.
tail además recorta el motivo del fallo, que el hook suele imprimir al principio.
Evita la tubería: git push ... > push.log 2>&1; echo $?, o usa set -o pipefail / ${PIPESTATUS[0]} en Bash y $LASTEXITCODE en PowerShell.
Verifica siempre el resultado real con git ls-remote origin refs/heads/main frente a git rev-parse HEAD.

Referencias

Vitest: ReferenceError: ResizeObserver is not defined

2026-10-29T09:00:00.000-05:00

Añades a la interfaz un componente que usa ResizeObserver (por ejemplo, una tabla con una barra de desplazamiento horizontal duplicada) y, de golpe, fallan muchos tests que no tienen relación entre sí:

 FAIL  src/TablaConScroll.test.tsx > TablaConScroll > muestra las filas
ReferenceError: ResizeObserver is not defined
 ❯ src/TablaConScroll.tsx:10:22
     10|     const observer = new ResizeObserver(() => setAncho(el.scrollWidth));

El componente de ejemplo mide su contenedor al montarse:

// src/TablaConScroll.tsx
import { useEffect, useRef, useState } from 'react';

export function TablaConScroll({ filas }: { filas: string[] }) {
  const contenedor = useRef<HTMLDivElement>(null);
  const [ancho, setAncho] = useState(0);

  useEffect(() => {
    const el = contenedor.current;
    if (!el) return;
    const observer = new ResizeObserver(() => setAncho(el.scrollWidth));
    observer.observe(el);
    return () => observer.disconnect();
  }, []);

  return (
    <div ref={contenedor} data-ancho={ancho}>
      <table>
        <tbody>
          {filas.map((f) => (
            <tr key={f}><td>{f}</td></tr>
          ))}
        </tbody>
      </table>
    </div>
  );
}

Funciona en el navegador, y los tests que no lo renderizan pasan. Este artículo explica por qué falla solo bajo jsdom y cómo resolverlo una vez, para toda la suite, con un archivo de preparación de Vitest.

Por qué pasa

jsdom es una implementación de la plataforma web para Node.js, pero no incluye todas las APIs de un navegador. Su propio README aclara que no calcula el diseño de la página (layout) y que devuelve ceros en muchas propiedades relacionadas, como getBoundingClientRect(). Un observador de tamaño necesita justo ese cálculo, y en el repositorio de jsdom, al escribir este artículo, la solicitud para implementar ResizeObserver seguía abierta como propuesta de nueva funcionalidad.

En la comprobación con Vitest 3.2.4 y jsdom 30.0.1, tanto typeof ResizeObserver como typeof IntersectionObserver devolvieron undefined, y getBoundingClientRect().width, scrollWidth y offsetWidth valían 0.

El error se multiplica porque el componente crea el observador dentro de un useEffect, que se ejecuta al montarlo. Cualquier test que lo renderice, directamente o dentro de una página o un layout que lo incluya, falla antes de llegar a sus aserciones.

Solución

Crea un archivo de preparación con un mock mínimo. La clase solo necesita los métodos que invoca tu código (aquí observe y disconnect); se incluyen los tres habituales por si otro componente usa unobserve. El operador ??= asigna únicamente si el global no existe, así que no pisa la implementación real en entornos que sí la tengan:

// vitest.setup.ts
class ResizeObserverMock {
  observe() {}
  unobserve() {}
  disconnect() {}
}

class IntersectionObserverMock {
  readonly root = null;
  readonly rootMargin = '';
  readonly thresholds: number[] = [];
  observe() {}
  unobserve() {}
  disconnect() {}
  takeRecords() {
    return [];
  }
}

globalThis.ResizeObserver ??= ResizeObserverMock as unknown as typeof ResizeObserver;
globalThis.IntersectionObserver ??=
  IntersectionObserverMock as unknown as typeof IntersectionObserver;

Regístralo en test.setupFiles. Según la documentación de Vitest, la ruta se resuelve respecto a la raíz del proyecto y los archivos se ejecutan antes de cada archivo de tests, en el mismo proceso:
```
// vitest.config.ts
import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    environment: 'jsdom',
    setupFiles: ['./vitest.setup.ts'],
  },
});
```
Si tu configuración de Vitest vive dentro de vite.config.ts, la clave test se escribe igual en ese archivo.

Cuando un test necesite controlar el observador, reemplaza el global solo en ese test con vi.stubGlobal y restáuralo después. Esta función está pensada para variables globales que no existen en jsdom o node; Vitest no las restablece por sí solo, así que llama a vi.unstubAllGlobals() (o activa la opción unstubGlobals de la configuración):

import { afterEach, expect, it, vi } from 'vitest';
import { act, cleanup, render } from '@testing-library/react';
import { TablaConScroll } from './TablaConScroll';

afterEach(() => {
  cleanup();
  vi.restoreAllMocks();
  vi.unstubAllGlobals();
});

it('reacciona cuando el observador notifica un cambio', () => {
  let notificar: () => void = () => {};

  class ObservadorControlado {
    constructor(callback: ResizeObserverCallback) {
      notificar = () => callback([], this as unknown as ResizeObserver);
    }
    observe = vi.fn();
    unobserve = vi.fn();
    disconnect = vi.fn();
  }
  vi.stubGlobal('ResizeObserver', ObservadorControlado);
  vi.spyOn(HTMLElement.prototype, 'scrollWidth', 'get').mockReturnValue(500);

  const { container } = render(<TablaConScroll filas={['uno']} />);
  act(() => notificar());

  expect(container.firstElementChild?.getAttribute('data-ancho')).toBe('500');
});

No dependas de medidas reales. Como jsdom no hace diseño, las anchuras y alturas son 0 salvo que las simules, como en el ejemplo anterior con scrollWidth. Los tests deben comprobar qué hace el componente cuando recibe una medida concreta, no cuánto mide en pantalla; para eso están las pruebas en un navegador real.
Alternativa: un polyfill. Puedes instalar el paquete resize-observer-polyfill e importarlo en el archivo de preparación en lugar de escribir el mock. Ten presente que seguirá sin haber medidas reales, porque jsdom no calcula el diseño.

Cómo verificar que quedó resuelto

npx vitest run

La suite debe terminar sin ReferenceError. En la prueba, antes de añadir el archivo de preparación fallaba el test del componente (Tests 1 failed | 1 passed) y después pasaron todos los archivos. Como comprobación permanente puedes añadir un test mínimo que detecte si alguien quita el archivo de la configuración:

import { expect, it } from 'vitest';

it('el entorno de tests define los observadores', () => {
  expect(typeof ResizeObserver).toBe('function');
  expect(typeof IntersectionObserver).toBe('function');
});

Variantes y errores relacionados

`IntersectionObserver is not defined`

Es el mismo caso: jsdom tampoco lo implementa, y el archivo de preparación de la solución 1 ya lo cubre. Si un test necesita simular que un elemento entra en pantalla, usa vi.stubGlobal con una clase que guarde el callback y llámalo a mano, igual que en el ejemplo del ResizeObserver.

`window.matchMedia is not a function` y `scrollIntoView is not a function`

En jsdom 30.0.1, typeof window.matchMedia y typeof Element.prototype.scrollIntoView también fueron undefined. Se resuelven con el mismo patrón:

if (typeof window !== 'undefined') {
  window.matchMedia ??= ((query: string) => ({
    matches: false,
    media: query,
    onchange: null,
    addEventListener() {},
    removeEventListener() {},
    addListener() {},
    removeListener() {},
    dispatchEvent: () => false,
  })) as unknown as typeof window.matchMedia;

  Element.prototype.scrollIntoView ??= function () {};
}

La condición typeof window !== 'undefined' importa: los archivos de setupFiles se ejecutan también en los archivos de tests que usan el entorno node, donde window no existe.

El error viene de una librería, no de tu código

Componentes de terceros (gráficos, listas virtualizadas, menús desplegables) suelen crear observadores internamente. La traza apunta entonces a node_modules, pero la solución es la misma: definir el global antes de que se monte el componente.

Cuidado con ocultar un fallo real

Un mock vacío hace que el test pase aunque el componente no reaccione a los cambios de tamaño. Si esa lógica es importante, cúbrela con un test como el de la solución 3, que dispara el callback a mano y comprueba el resultado.

Resumen

jsdom no implementa ResizeObserver ni IntersectionObserver; cualquier componente que los use al montarse rompe todos los tests que lo rendericen.
Define un mock con observe, unobserve y disconnect en un archivo registrado en test.setupFiles, con globalThis.ResizeObserver ??= ....
Para controlar el observador en un test concreto, usa vi.stubGlobal y vi.unstubAllGlobals().
En jsdom las medidas de diseño son 0: simula los valores que necesites y no escribas tests que dependan de tamaños reales.

Tutoriales Técnicos

React Hook Form: trigger() dice Required con el campo lleno

Por qué pasa

Solución

Cómo verificar que quedó resuelto

Variantes y errores relacionados

Mismo fallo con register

Otros hooks que reciben control

FormProvider

El mensaje cambia con el esquema

Resumen

Referencias

React: key={index} hace que una fila pise a otra

Por qué pasa

1. El índice no identifica a la fila

2. Los cierres ven una instantánea del estado

3. Quitar con estado capturado

Solución

Cómo verificar que quedó resuelto

Variantes y errores relacionados

key={Math.random()} o un uuid dentro del JSX

Cuándo el índice sí es aceptable

Filas que ya vienen de una API

React Hook Form con useFieldArray

Cambiar la clave a propósito

Resumen

Referencias

shadcn/ui Table: sticky y scroll horizontal no funcionan

Por qué pasa

Solución

Cómo verificar que quedó resuelto

Variantes y errores relacionados

La tabla se monta después del contenedor

"ResizeObserver loop completed with undelivered notifications"

Solo quieres el encabezado fijo

El sticky sigue sin funcionar

Resumen

Referencias

El title de un botón disabled no aparece (shadcn/ui)

Por qué pasa

Solución

Cómo verificar que quedó resuelto

Variantes y errores relacionados

Los clics atraviesan el botón deshabilitado

Usar aria-disabled en lugar de disabled

Las limitaciones del atributo title

Resumen

Referencias

Modal sin scroll en pantallas de poca altura (CSS)

Por qué pasa

Solución

Cómo verificar que quedó resuelto

Variantes y errores relacionados

Una media query de altura para compactar el diseño

vh, dvh o svh

El mismo fallo en otros contenedores

Resumen

Referencias

El texto de la pestaña activa desaparece al pasar el mouse

Por qué pasa

Solución

Cómo verificar que quedó resuelto

Variantes y errores relacionados

El mismo conflicto con :focus, :active o :disabled

Si el hover cambia también el fondo

No uses !important como atajo

No dependas del orden entre archivos

Resumen

Referencias

ESLint: "is defined but never used" en componentes JSX

Por qué pasa

Solución

Cómo verificar que quedó resuelto

Variantes y errores relacionados

La alternativa de la plantilla: varsIgnorePattern

Proyectos con TypeScript

¿Y react/jsx-uses-react?

La regla no tiene efecto

Resumen

Referencias

Mismo fallo con `register`

Otros hooks que reciben `control`

`key={Math.random()}` o un uuid dentro del JSX

Usar `aria-disabled` en lugar de `disabled`

Las limitaciones del atributo `title`

`vh`, `dvh` o `svh`

El mismo conflicto con `:focus`, `:active` o `:disabled`

No uses `!important` como atajo

La alternativa de la plantilla: `varsIgnorePattern`

¿Y `react/jsx-uses-react`?

Un `Host *` al principio del archivo

No silencies el problema con `core.fileMode = false` en el servidor

Sigue apareciendo `rateLimitExceeded` con tu propio client_id

Sigue saliendo `DNS_PROBE_FINISHED_NXDOMAIN` justo después de crear el registro

Redirigir al revés (de la raíz a `www`)

Solo un workflow en `startup_failure`