Skip to main content
Most issues with Luminy fall into a small set of categories: the local model provider isn’t running, a model doesn’t support tool use, a project didn’t index cleanly, or an API key was entered incorrectly. This page walks through the most common problems and how to fix them quickly.
Luminy can’t reach Ollama when the Ollama process isn’t running or when the endpoint in Settings doesn’t match where Ollama is listening.Steps to fix:
  1. Open a terminal and run: 
    ollama serve
    If Ollama is already running, this will print a message saying so. If not, it starts the server.
  2. Confirm Ollama is responding: 
    ollama list
    This should return a list of your pulled models. If it errors, Ollama is not running.
  3. In Luminy, go to Settings → Providers → Ollama and verify the endpoint is: 
    http://localhost:11434
    If you’ve changed Ollama’s default port or are running it in a container, update this field to match.
  4. If you’re on macOS and installed Ollama as an app, make sure the menu bar icon is visible and showing “Running”.
Ollama must be running before you open Luminy, or you must restart the Ollama connection in Settings after starting the server.
If the agent is responding in plain text instead of calling tools, reading files, or making edits, your model likely does not support function calling (tool use).What’s happening: Not all Ollama models support the structured tool-call format that Luminy requires for agentic behavior. Text-only models will respond conversationally but cannot invoke tools.Steps to fix:
  1. Switch to a model that explicitly supports tool calling. Recommended: 
    ollama pull qwen2.5-coder:7b
ollama pull qwen2.5-coder:32b
  2. Alternatively, switch to a cloud provider (Anthropic Claude, OpenAI GPT-4o, Google Gemini) — all of these have reliable tool support.
  3. In Luminy, open the model selector at the bottom of the chat and choose your new model.
When in doubt, qwen2.5-coder is the most reliable locally-hosted model for Luminy’s agentic tool loop.
If the indexing spinner doesn’t complete, or the agent reports it can’t find files you know exist, the project index may have stalled or failed silently.Steps to fix:
  1. Go to Settings → Projects and remove the affected project.
  2. Re-add the same folder by clicking Add Project.
  3. Wait for the indexing spinner to complete fully before sending a message.
Other things to check:
  • Make sure the project folder still exists at the path Luminy has stored. If you moved or renamed the folder, remove and re-add it.
  • Check that Luminy has filesystem read permissions for that directory (especially on macOS with strict app sandboxing).
  • Very large repositories (100,000+ files) can take several minutes to index on first add. Leave the app open and wait.
Indexing supports deep symbol-level understanding for Python, JavaScript, TypeScript, Rust, Go, Java, C++, and C#. Other file types are still readable by the agent — they just don’t get symbol-level indexing.
If Luminy shows an authentication error, a 401, or the model selector shows your cloud provider as unavailable, the API key may not be saved correctly or may have an issue on the provider’s side.Steps to fix:
  1. Go to Settings → Providers and locate the affected provider.
  2. Delete the existing key and re-enter it. Click Save — do not just close the panel.
  3. Double-check for accidental leading or trailing spaces in the key field.
  4. Log in to the provider’s dashboard (Anthropic Console, OpenAI Platform, Google AI Studio) and confirm:
    • The key is active and not expired or revoked.
    • Your account has sufficient credits or is within its rate limits.
    • The key has the correct permissions (some providers issue read-only or project-scoped keys).
API keys are stored locally in Luminy’s SQLite database on your device. They are never sent to Luminy’s servers. If you’re rotating a compromised key, revoke it in the provider’s dashboard — Luminy cannot do this for you.
When you download Luminy and try to open it on macOS, you may see a dialog saying the app “cannot be opened because it is from an unidentified developer” or similar Gatekeeper messaging.Steps to fix:
  1. In Finder, locate the Luminy app (usually in your Applications folder or Downloads).
  2. Right-click (or Control-click) the app icon.
  3. Select Open from the context menu.
  4. In the dialog that appears, click Open to confirm.
This is a one-time step. After you’ve approved Luminy this way, it will open normally on every subsequent launch.
This happens because Luminy is distributed outside the Mac App Store. The right-click → Open bypass is the standard macOS workflow for trusted third-party apps. You only need to do it once per installation.
Compaction summarizes older turns automatically, but in extremely long sessions with very large files or many tool calls, the context can become saturated beyond what compaction can recover.Steps to fix:
  1. Start a new session. This gives you a completely fresh context window. You can still refer back to the old session in the sidebar.
  2. Fork from a recent checkpoint. Open the session, find the last message that represents a stable state (e.g., after a feature was completed), and fork from there. The fork starts fresh from that point.
  3. Switch to a model with a larger context window. For example:
    • Gemini 2.0 Flash: 1 million tokens
    • Claude 3.5 Sonnet: 200k tokens
    • GPT-4o: 128k tokens
For very long coding sessions, proactively fork at key milestones (after a feature ships, after a big refactor) rather than waiting until the context is saturated.
If an MCP server you’ve added shows as disconnected or Luminy can’t invoke its tools, the most common causes are a missing executable in PATH, a configuration error, or the server process crashing on startup.Steps to fix:
  1. Check the server command is installed and accessible. For example, if your MCP server uses npx: 
    which npx
npx --version
    If which returns nothing, the binary is not in your PATH. Install it or use the full absolute path in the MCP config.
  2. Try running the MCP server command manually in your terminal to see if it starts cleanly or prints an error: 
    npx -y @your-mcp-server/package
  3. Check Luminy’s app logs. On macOS, open Console.app and filter for “Luminy”. On all platforms, logs may also appear in the developer console (if you’re running a dev build).
  4. Verify the MCP configuration in Luminy — make sure the command string, arguments, and any required environment variables are correct.
Slow token generation is almost always a hardware constraint: the model is too large to fit in your GPU’s VRAM and is falling back to slower CPU inference or memory-swapping.Steps to fix:
  1. Check whether Ollama is using your GPU: 
    ollama ps
    Look at the PROCESSOR column. If it says 100% CPU for a large model, your GPU isn’t being used.
  2. Switch to a smaller or more quantized model. As a rough guide:
    • 4–6 GB VRAM → use 7B models (e.g., qwen2.5-coder:7b)
    • 10–12 GB VRAM → use 14B models
    • 24 GB+ VRAM → 32B models become viable
  3. Try a quantized version of your current model (e.g., Q4_K_M instead of Q8_0). Quantized models use significantly less VRAM with a small quality tradeoff.
  4. Alternatively, switch to a cloud provider (Anthropic, OpenAI, Gemini) for faster inference without local hardware constraints.
If you see the agent calling the same tool in a loop without making progress, Luminy will automatically stop the run after detecting the repeated pattern.Steps to fix:
  1. After the agent stops, try rephrasing your original request with more specific instructions about what you want the agent to do differently.
  2. If the loop was triggered by a specific file or command, try breaking the task into smaller steps — ask the agent to do just one part at a time.
  3. Fork the session from the last good message before the loop started and try a fresh approach from that checkpoint.
  4. If the issue recurs with the same model, try switching to a more capable model — getting stuck in a loop often indicates the model is confused about the task structure.
Luminy automatically generates a session title from the content of your first message. If the title shows as blank or never appears, the title generation request likely failed silently.Steps to fix:
  1. Rename the session manually. Right-click the session in the sidebar (or click the three-dot menu) and select Rename. Enter a name and press Enter.
  2. If title generation is consistently failing, check that the model you’re using is responsive — a model that’s timing out or returning errors won’t generate a title either.
  3. For cloud providers, verify your API key is valid and your account isn’t rate-limited (title generation uses a small separate request after your first message).