Cursos/Claude Code + IA Local/Soluciona errores de Ollama

Soluciona errores de Ollama en Windows, macOS y Linux

La mayoría de fallos con IA local no son misteriosos: servicio apagado, modelo mal escrito, puerto incorrecto, falta de memoria o expectativas demasiado altas para el hardware. Esta guía te da un diagnóstico rápido antes de perder la tarde.

Objetivos de aprendizaje
  • Diagnosticar si Ollama está instalado, arrancado y accesible.
  • Resolver errores típicos al conectar apps, Claude Code o pasarelas.
  • Ajustar modelo y flujo cuando el equipo se queda corto.
En cristiano: localhost:11434. Es la dirección de Ollama dentro de tu propio ordenador. Si una app no puede conectar con esa dirección, el problema suele estar en que Ollama no está arrancado, el puerto cambió o la app está ejecutándose en otro entorno.

Diagnóstico de 60 segundos

Terminal
ollama --version
ollama list
ollama ps
curl http://localhost:11434/api/tags
Comprueba que funciona. Si api/tags devuelve una lista de modelos, Ollama está vivo. Si falla ahí, no sigas tocando tu app: arregla primero Ollama.

Error: connection refused

Significa que tu programa llama a localhost:11434, pero no hay nada escuchando.

Terminal
ollama serve

En macOS y Windows, Ollama normalmente arranca como app de escritorio. Si cerraste la app, vuelve a abrirla. En Linux, revisa el servicio:

Terminal
systemctl status ollama
sudo systemctl restart ollama

Error: model not found

El nombre que usas en tu app no coincide con el modelo instalado.

Terminal
ollama list
ollama pull qwen3:4b
Idea clave. Copia el nombre exacto que aparece en ollama list. qwen3, qwen3:4b y ollama/qwen3:4b pueden significar cosas distintas según la herramienta.

Ollama responde muy lento

  • Baja a un modelo más pequeño: 1B, 3B o 4B.
  • Cierra apps pesadas antes de lanzar el modelo.
  • Reduce contexto y documentos de entrada.
  • Usa el flujo híbrido: Claude Code para construir, Ollama para procesar datos privados o repetitivos.
Cuidado. Si tu equipo entra en intercambio de memoria, todo se vuelve lentísimo. No es “culpa de la IA”: el modelo no cabe cómodo. Cambia a uno más pequeño y vuelve a probar.

La app funciona en terminal, pero no desde Docker

Dentro de un contenedor, localhost apunta al contenedor, no a tu ordenador. Prueba con el host de Docker:

Terminal
http://host.docker.internal:11434

LiteLLM o una pasarela no conecta

Primero prueba Ollama directo. Después revisa el archivo de configuración de la pasarela.

Terminal
curl http://localhost:11434/api/tags

# En LiteLLM, el modelo suele declararse así:
model: ollama/qwen3:4b
api_base: http://localhost:11434

Checklist final

  • El comando ollama --version funciona.
  • ollama list muestra el modelo exacto.
  • curl /api/tags responde.
  • Tu app apunta a http://localhost:11434 o al host correcto si usa Docker.
  • El modelo cabe en tu RAM sin bloquear el equipo.
Guardar y reabrir el proyecto.
Cuando algo falle, guarda el error exacto, el sistema operativo, el modelo y la salida de los cuatro comandos de diagnóstico. Con eso, cualquier asistente o foro puede ayudarte mucho mejor.
← Conecta Claude Code con tu IA localOllama no usa la GPU en Windows →