> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/pfrankov/obsidian-local-gpt/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Common issues and solutions for Local GPT

# Troubleshooting

This guide covers common issues you might encounter when using Local GPT and how to resolve them.

## AI Provider Connection Issues

### Cannot Connect to Local AI Server

<AccordionGroup>
  <Accordion title="Symptom">
    Error messages like:

    * "Error while generating text: Failed to fetch"
    * "Network request failed"
    * Provider shows as unavailable in settings
  </Accordion>

  <Accordion title="Causes & Solutions">
    <Steps>
      <Step title="Verify Server is Running">
        **For Ollama:**

        ```bash theme={null}
        # Check if Ollama is running
        ollama list

        # Start Ollama if needed
        ollama serve
        ```

        **For LM Studio:**

        * Open LM Studio
        * Click "Local Server" tab
        * Ensure server is started on port 8080 (or your configured port)
      </Step>

      <Step title="Check URL Configuration">
        Default URLs:

        * **Ollama**: `http://localhost:11434`
        * **LM Studio**: `http://localhost:8080/v1`

        Verify in **Settings → AI Providers → \[Your Provider]**
      </Step>

      <Step title="Test Connection Manually">
        Open a terminal and test:

        ```bash theme={null}
        # For Ollama
        curl http://localhost:11434/api/tags

        # For OpenAI-compatible (LM Studio, etc.)
        curl http://localhost:8080/v1/models
        ```

        If these fail, the server is not accessible.
      </Step>

      <Step title="Check Firewall">
        Ensure your firewall allows connections to:

        * Port 11434 (Ollama)
        * Port 8080 (LM Studio, or your configured port)

        On macOS:

        ```bash theme={null}
        sudo /usr/libexec/ApplicationFirewall/socketfilterfw --add /path/to/ollama
        ```
      </Step>

      <Step title="Verify CORS (if applicable)">
        If running Obsidian in a sandboxed environment, CORS may block requests.

        For LM Studio, enable CORS in server settings.
      </Step>
    </Steps>
  </Accordion>
</AccordionGroup>

### Cloud API Authentication Errors

<AccordionGroup>
  <Accordion title="Symptom">
    * "Invalid API key"
    * "Unauthorized" (401 error)
    * "Authentication failed"
  </Accordion>

  <Accordion title="Solutions">
    <Steps>
      <Step title="Verify API Key">
        1. Go to **Settings → AI Providers → \[Your Provider]**
        2. Check that the API key is entered correctly (no extra spaces)
        3. Confirm the key is valid in your provider's dashboard:
           * OpenAI: [platform.openai.com/api-keys](https://platform.openai.com/api-keys)
           * Anthropic: [console.anthropic.com/settings/keys](https://console.anthropic.com/settings/keys)
      </Step>

      <Step title="Check Key Permissions">
        Ensure your API key has permission to:

        * Access the model you're trying to use
        * Make chat completions (not just embeddings)
      </Step>

      <Step title="Regenerate Key if Needed">
        If issues persist, generate a new API key in your provider's dashboard and update Local GPT.
      </Step>
    </Steps>
  </Accordion>
</AccordionGroup>

### Model Not Found

<AccordionGroup>
  <Accordion title="Symptom">
    * "Model not found"
    * "Unknown model"
    * Model doesn't appear in dropdown
  </Accordion>

  <Accordion title="Solutions">
    <Steps>
      <Step title="Pull/Download the Model">
        **For Ollama:**

        ```bash theme={null}
        # List available models
        ollama list

        # Pull the model if missing
        ollama pull llama3.2
        ```

        **For LM Studio:**

        * Search for the model in the "Discover" tab
        * Click "Download"
        * Wait for download to complete
      </Step>

      <Step title="Verify Model Name">
        Model names must match exactly, including version tags:

        * ✅ `llama3.2:latest`
        * ❌ `llama3.2` (missing tag for Ollama)
        * ✅ `gpt-4-turbo`
        * ❌ `gpt4-turbo` (incorrect hyphenation)
      </Step>

      <Step title="Refresh Model List">
        In Local GPT settings:

        1. Go to the provider configuration
        2. Open the model dropdown
        3. The list should refresh automatically
      </Step>

      <Step title="Check Provider URL">
        If models don't load, verify the provider URL is correct (see "Cannot Connect" above).
      </Step>
    </Steps>
  </Accordion>
</AccordionGroup>

## Embedding Model Issues

### Embedding Model Not Found

<AccordionGroup>
  <Accordion title="Symptom">
    * Enhanced Actions (RAG) don't work
    * "Error processing related documents"
    * No embedding provider configured warning
  </Accordion>

  <Accordion title="Solutions">
    <Steps>
      <Step title="Configure Embedding Provider">
        1. Go to **Settings → AI Providers**
        2. Find **Embedding AI Provider**
        3. Select a provider from the dropdown
      </Step>

      <Step title="Download an Embedding Model">
        **For Ollama (recommended):**

        ```bash theme={null}
        # Pull a popular embedding model
        ollama pull nomic-embed-text
        ```

        Other good options:

        * `mxbai-embed-large`
        * `all-minilm`
      </Step>

      <Step title="Verify Model in Provider">
        After downloading:

        1. In AI Providers settings, edit your Ollama provider
        2. Ensure the embedding model is listed
        3. Save the provider configuration
      </Step>

      <Step title="Set as Embedding Provider">
        Return to **Embedding AI Provider** dropdown and select your configured provider.
      </Step>
    </Steps>

    <Info>
      Embedding models are separate from chat models. You need both for Enhanced Actions to work.
    </Info>
  </Accordion>
</AccordionGroup>

### Enhanced Actions Not Working

<AccordionGroup>
  <Accordion title="Symptom">
    * RAG doesn't include linked documents
    * No context from vault files
    * Status bar doesn't show "✨ Enhancing"
  </Accordion>

  <Accordion title="Checklist">
    <Steps>
      <Step title="Verify Links Exist">
        Enhanced Actions require:

        * Wiki-links: `[[Document Name]]`
        * Markdown links: `[text](path/to/file.md)`

        In your selection or prompt
      </Step>

      <Step title="Check Embedding Provider">
        Confirm in **Settings → AI Providers → Embedding AI Provider** that a provider is selected.
      </Step>

      <Step title="Check Context Limit">
        In **Settings → Advanced Settings → RAG context**:

        * Ensure it's not set too low
        * Try "Cloud models" (32K) or higher
      </Step>

      <Step title="Verify File Types">
        Only these file types are processed:

        * `.md` (Markdown)
        * `.pdf` (PDF documents)
      </Step>

      <Step title="Look for Errors">
        Check the Developer Console:

        1. Press `Ctrl+Shift+I` (Windows/Linux) or `Cmd+Option+I` (Mac)
        2. Look for errors related to "RAG" or "embedding"
      </Step>
    </Steps>
  </Accordion>
</AccordionGroup>

## Performance Issues

### Slow Response Times

<AccordionGroup>
  <Accordion title="Local Model is Slow">
    **Causes:**

    * Model is too large for your hardware
    * Insufficient RAM/VRAM
    * CPU inference instead of GPU

    **Solutions:**

    <Steps>
      <Step title="Use a Smaller Model">
        Switch to a quantized or smaller model:

        * Instead of `llama3.2:70b` → try `llama3.2:8b`
        * Instead of `mistral:7b` → try `mistral:7b-q4_0` (quantized)
      </Step>

      <Step title="Enable GPU Acceleration">
        **For Ollama:**

        * Ensure CUDA (NVIDIA) or ROCm (AMD) is installed
        * Verify GPU is detected: `ollama ps`

        **For LM Studio:**

        * Settings → Hardware → Enable GPU offloading
        * Increase GPU layers if you have VRAM
      </Step>

      <Step title="Reduce Context">
        Lower **Settings → Advanced → RAG context** to reduce token count.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Enhanced Actions Take Too Long">
    **Causes:**

    * Too many linked documents
    * Large PDF files
    * High context limit

    **Solutions:**

    <Steps>
      <Step title="Reduce Link Depth">
        Link fewer documents directly or reduce graph complexity.
      </Step>

      <Step title="Lower Context Limit">
        Change **RAG context** from "Advanced" to "Cloud models" or "Local models".
      </Step>

      <Step title="Use Faster Embedding Model">
        Switch to a smaller, faster embedding model:

        * `all-minilm` (fast, decent quality)
        * `nomic-embed-text` (balanced)
      </Step>
    </Steps>
  </Accordion>
</AccordionGroup>

### High Memory Usage

<AccordionGroup>
  <Accordion title="Symptom">
    * Obsidian becomes slow or unresponsive
    * System memory fills up
    * App crashes
  </Accordion>

  <Accordion title="Solutions">
    <Steps>
      <Step title="Clear IndexedDB Cache">
        The PDF cache may grow large. To clear:

        1. Open Developer Console (`Ctrl+Shift+I` / `Cmd+Option+I`)
        2. Go to **Application** tab
        3. Find **IndexedDB → local-gpt-file-cache**
        4. Right-click → Delete database
      </Step>

      <Step title="Reduce Concurrent Processing">
        Avoid triggering multiple AI requests simultaneously.
      </Step>

      <Step title="Use Smaller Context Limits">
        Lower limits reduce memory usage during RAG processing.
      </Step>
    </Steps>
  </Accordion>
</AccordionGroup>

## Quality Issues

### Poor Response Quality

<AccordionGroup>
  <Accordion title="Responses are Generic or Off-Topic">
    **Possible causes:**

    * Insufficient context
    * Wrong creativity setting
    * Model not suited for the task

    **Solutions:**

    <Steps>
      <Step title="Increase Context">
        Raise **RAG context** to include more information from linked documents.
      </Step>

      <Step title="Adjust Creativity">
        In **Settings → Creativity**:

        * Too creative → Lower to "Low" or "None"
        * Too rigid → Increase to "Medium" or "High"
      </Step>

      <Step title="Use a Better Model">
        Switch to a more capable model:

        * Local: Try `llama3.2:70b` or `mixtral:8x7b`
        * Cloud: Try `gpt-4-turbo` or `claude-3-opus`
      </Step>

      <Step title="Improve System Prompt">
        Edit your action's system prompt to be more specific about what you need.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Responses are Too Verbose or Unfocused">
    **Possible causes:**

    * Too much context overwhelms the model
    * High creativity setting

    **Solutions:**

    <Steps>
      <Step title="Reduce Context Limit">
        Lower **RAG context** to focus on most relevant information only.
      </Step>

      <Step title="Lower Creativity">
        Set **Creativity** to "None" or "Low" for more focused responses.
      </Step>

      <Step title="Be More Specific in Prompts">
        Add constraints like:

        * "Answer in 2-3 sentences"
        * "Focus only on X"
        * "Be concise"
      </Step>
    </Steps>
  </Accordion>
</AccordionGroup>

## Logging and Debugging

### Enable Development Logging

To see detailed logs:

<Steps>
  <Step title="Set Environment Variable">
    Add to your build command:

    ```bash theme={null}
    NODE_ENV=development npm run dev
    ```
  </Step>

  <Step title="Open Developer Console">
    Press `Ctrl+Shift+I` (Windows/Linux) or `Cmd+Option+I` (Mac)
  </Step>

  <Step title="View Logs">
    Look for logs with emoji prefixes:

    * 🐛 Debug information
    * ℹ️ General info
    * ⚠️ Warnings
    * 🚫 Errors
    * ⏱️ Performance timing
    * 📊 Data tables
  </Step>
</Steps>

### Understanding Log Output

<CodeGroup>
  ```javascript Development Logs theme={null}
  // Processing starts
  ℹ️ Starting RAG processing

  // Context limit info
  ℹ️ Passed contextLimit for context: 32000

  // PDF extraction
  ⏱️ Extracting text from PDF: timer started
  📊 Extracted text from PDF
    textLength: 45231
  ⏱️ Extracting text from PDF: 1234.56ms

  // Final context length
  📊 Total length of context: 28945
  ```

  ```javascript Error Logs theme={null}
  // Connection errors
  🚫 Error processing document /path/to/file.pdf: Error: ...

  // Translation warnings
  ⚠️ Translation missing: settings.newKey

  // Request failures
  🚫 Error in searchDocuments: Error: ...
  ```
</CodeGroup>

### Common Error Messages

<AccordionGroup>
  <Accordion title="Error: No AI provider found">
    **Cause:** No main AI provider is configured.

    **Solution:** Go to **Settings → AI Providers → Main AI Provider** and select a provider.
  </Accordion>

  <Accordion title="Error processing related documents: [message]">
    **Cause:** RAG processing failed but execution continued.

    **Solution:**

    1. Check embedding provider configuration
    2. Verify linked files exist and are readable
    3. Check Developer Console for detailed error
  </Accordion>

  <Accordion title="Failed to extract text from PDF: [message]">
    **Cause:** PDF file is corrupted, password-protected, or unsupported.

    **Solution:**

    1. Try opening the PDF in another app
    2. If password-protected, remove protection
    3. If scanned images, use OCR to create searchable PDF
  </Accordion>

  <Accordion title="Translation missing: [key]">
    **Cause:** A translation key doesn't exist in your language file.

    **Impact:** You'll see English text for that string.

    **Solution:** This is not critical but can be [reported as an issue](https://github.com/pfrankov/obsidian-local-gpt/issues) or fixed via translation contribution.
  </Accordion>
</AccordionGroup>

## How to Report Bugs

If you encounter an issue not covered here:

<Steps>
  <Step title="Gather Information">
    Collect:

    * Obsidian version
    * Local GPT version (Settings → Community Plugins → Local GPT)
    * Operating system
    * Error messages from Developer Console
    * Steps to reproduce
  </Step>

  <Step title="Check Existing Issues">
    Search [GitHub Issues](https://github.com/pfrankov/obsidian-local-gpt/issues) to see if it's already reported.
  </Step>

  <Step title="Create a New Issue">
    If not found, [open a new issue](https://github.com/pfrankov/obsidian-local-gpt/issues/new) with:

    * **Clear title**: "\[Component] Brief description"
    * **Description**: What happened vs. what you expected
    * **Steps to reproduce**: Numbered list
    * **Logs**: Relevant console output
    * **Environment**: OS, versions, AI provider used
  </Step>

  <Step title="Provide Minimal Example">
    If possible, create a minimal test case:

    * Small vault with just the files needed to reproduce
    * Specific action that triggers the issue
    * Sample text or prompts
  </Step>
</Steps>

<Warning>
  **Never include API keys or sensitive data** when sharing logs or examples!
</Warning>

## Source Code References

For developers debugging issues, relevant source files:

<CardGroup cols={2}>
  <Card title="Logger" icon="terminal">
    `src/logger.ts` - Logging system (lines 1-186)
  </Card>

  <Card title="Error Handling" icon="shield-exclamation">
    `src/main.ts:649-660` - Provider request error handling
  </Card>

  <Card title="RAG Errors" icon="triangle-exclamation">
    `src/main.ts:803-817` - Context processing error handling
  </Card>

  <Card title="PDF Processing" icon="file-pdf">
    `src/processors/pdf.ts:38-41` - PDF extraction errors
  </Card>
</CardGroup>

## Getting Help

If you're still stuck:

<CardGroup cols={2}>
  <Card title="GitHub Discussions" icon="comments" href="https://github.com/pfrankov/obsidian-local-gpt/discussions">
    Ask questions and get community support
  </Card>

  <Card title="GitHub Issues" icon="bug" href="https://github.com/pfrankov/obsidian-local-gpt/issues">
    Report bugs and technical problems
  </Card>

  <Card title="Documentation" icon="book" href="/">
    Browse the full documentation
  </Card>

  <Card title="Contributing" icon="code-pull-request" href="https://github.com/pfrankov/obsidian-local-gpt/blob/master/CONTRIBUTING.md">
    Help improve Local GPT
  </Card>
</CardGroup>