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

# Troubleshooting

> Common issues and solutions for Perplexica deployment

This guide covers common issues you might encounter when deploying or running Perplexica, along with their solutions.

## Connection errors

### Ollama connection errors

If you're encountering an Ollama connection error, it's likely due to the backend being unable to connect to Ollama's API.

<Steps>
  <Step title="Verify API URL">
    Check that your Ollama API URL is correctly set in the Perplexica settings menu.
  </Step>

  <Step title="Update API URL based on OS">
    The correct URL varies by operating system:

    <CodeGroup>
      ```bash Windows theme={null}
      http://host.docker.internal:11434
      ```

      ```bash macOS theme={null}
      http://host.docker.internal:11434
      ```

      ```bash Linux theme={null}
      http://<private_ip_of_host>:11434
      ```
    </CodeGroup>

    <Note>
      Adjust the port number if you're using a different port than the default 11434.
    </Note>
  </Step>

  <Step title="Linux users: Expose Ollama to network">
    On Linux, you need to configure Ollama to listen on all network interfaces:

    1. Edit the Ollama service file:

    ```bash theme={null}
    sudo nano /etc/systemd/system/ollama.service
    ```

    2. Add the following line in the `[Service]` section:

    ```ini theme={null}
    Environment="OLLAMA_HOST=0.0.0.0:11434"
    ```

    Change the port number if using a different one.

    3. Reload systemd and restart Ollama:

    ```bash theme={null}
    systemctl daemon-reload
    systemctl restart ollama
    ```

    4. Ensure port 11434 is not blocked by your firewall:

    ```bash theme={null}
    sudo ufw allow 11434
    ```

    For more information, see the [Ollama documentation](https://github.com/ollama/ollama/blob/main/docs/faq.md#setting-environment-variables-on-linux).
  </Step>
</Steps>

### Lemonade connection errors

If you're encountering a Lemonade connection error, the backend cannot connect to Lemonade's API.

<Steps>
  <Step title="Check Lemonade API URL">
    Ensure the API URL is correctly configured in the Perplexica settings menu.
  </Step>

  <Step title="Update API URL based on OS">
    <CodeGroup>
      ```bash Windows theme={null}
      http://host.docker.internal:8000
      ```

      ```bash macOS theme={null}
      http://host.docker.internal:8000
      ```

      ```bash Linux theme={null}
      http://<private_ip_of_host>:8000
      ```
    </CodeGroup>

    Adjust the port number if using a different one than the default 8000.
  </Step>

  <Step title="Verify Lemonade is running">
    Ensure your Lemonade server is:

    * Running and accessible on the configured port (default: 8000)
    * Configured to accept connections from all interfaces (`0.0.0.0`), not just localhost (`127.0.0.1`)
    * Not blocked by firewall on the specified port
  </Step>
</Steps>

### Local OpenAI-compatible servers

If Perplexica tells you that you haven't configured any chat model providers:

<AccordionGroup>
  <Accordion title="Server binding address">
    Ensure your server is running on `0.0.0.0` (not `127.0.0.1`) and on the same port you specified in the API URL.

    Many local LLM servers default to localhost only, which won't be accessible from inside a Docker container.
  </Accordion>

  <Accordion title="Model name">
    Verify you've specified the correct model name as loaded by your local LLM server. The model name must exactly match what your server expects.
  </Accordion>

  <Accordion title="API key">
    Even if your local server doesn't require an API key, Perplexica's form validation requires something in the API key field. Enter any non-empty value if your server doesn't use authentication.
  </Accordion>
</AccordionGroup>

## SearxNG issues

### SearxNG not responding

If searches are failing or timing out:

<Steps>
  <Step title="Check SearxNG status">
    For Docker deployments with bundled SearxNG, check if it's running:

    ```bash theme={null}
    docker logs perplexica | grep SearXNG
    ```

    You should see:

    ```
    Starting SearXNG...
    SearXNG started successfully
    ```
  </Step>

  <Step title="Verify SearxNG accessibility">
    Test the SearxNG endpoint directly:

    ```bash theme={null}
    curl http://localhost:8080
    ```

    You should receive HTML content from SearxNG.
  </Step>

  <Step title="Check JSON format">
    Ensure JSON format is enabled in SearxNG settings. This is required for Perplexica to parse search results.
  </Step>

  <Step title="Verify Wolfram Alpha">
    Confirm Wolfram Alpha search engine is enabled in SearxNG for mathematical queries and calculations.
  </Step>
</Steps>

### External SearxNG connection

When using the slim image with your own SearxNG:

<Warning>
  Make sure you've set the `SEARXNG_API_URL` environment variable when starting the container, and that your SearxNG instance is accessible from the Docker container.
</Warning>

```bash theme={null}
docker run -d -p 3000:3000 -e SEARXNG_API_URL=http://your-searxng-url:8080 -v perplexica-data:/home/perplexica/data --name perplexica itzcrazykns1337/perplexica:slim-latest
```

## Docker issues

### Port already in use

If you see an error about port 3000 or 8080 already being in use:

<CodeGroup>
  ```bash Check what's using the port theme={null}
  sudo lsof -i :3000
  ```

  ```bash Use a different port theme={null}
  docker run -d -p 3001:3000 -v perplexica-data:/home/perplexica/data --name perplexica itzcrazykns1337/perplexica:latest
  ```

  ```bash Stop conflicting container theme={null}
  docker stop <container-name>
  ```
</CodeGroup>

### Volume permission issues

If you encounter permission errors with the data volume:

```bash theme={null}
# Check volume permissions
docker volume inspect perplexica-data

# If needed, recreate the volume
docker volume rm perplexica-data
docker volume create perplexica-data
```

### Container won't start

Check the container logs for specific errors:

```bash theme={null}
docker logs perplexica
```

Common issues:

* Missing environment variables
* Port conflicts
* Volume mount problems
* Insufficient resources (RAM/CPU)

## Application issues

### Searches return no results

<AccordionGroup>
  <Accordion title="Check SearxNG connection">
    Verify that SearxNG is running and accessible. Check the Perplexica logs for connection errors.
  </Accordion>

  <Accordion title="Verify LLM provider">
    Ensure your AI provider (OpenAI, Anthropic, Ollama, etc.) is properly configured with valid API keys and model names.
  </Accordion>

  <Accordion title="Test with different search modes">
    Try switching between Speed, Balanced, and Quality modes to see if the issue is mode-specific.
  </Accordion>
</AccordionGroup>

### Slow search responses

* **Check your internet connection**: Web searches require good connectivity
* **Try Speed mode**: Quality mode is more thorough but slower
* **Local LLM performance**: If using Ollama, ensure your hardware can handle the model
* **SearxNG response time**: External SearxNG instances may be slower

### File upload failures

<Steps>
  <Step title="Check volume mount">
    Ensure the uploads directory is properly mounted:

    ```bash theme={null}
    docker exec perplexica ls -la /home/perplexica/uploads
    ```
  </Step>

  <Step title="Verify file size">
    Check if the file is within acceptable limits (exact limits depend on configuration).
  </Step>

  <Step title="Check file format">
    Perplexica supports PDFs, text files, and images. Other formats may not be supported.
  </Step>
</Steps>

### Settings not persisting

If your settings reset after container restart:

```bash theme={null}
# Ensure you're using a named volume
docker run -d -p 3000:3000 -v perplexica-data:/home/perplexica/data --name perplexica itzcrazykns1337/perplexica:latest

# NOT a bind mount to a non-existent directory
```

The `-v perplexica-data:/home/perplexica/data` flag is essential for persistence.

## Performance issues

### High memory usage

Perplexica uses AI models which can be memory-intensive:

* Minimum: 1GB RAM
* Recommended: 2GB+ RAM
* With local LLMs (Ollama): 4GB+ RAM depending on model size

### High CPU usage

* Normal during active searches with local LLMs
* Consider using cloud API providers (OpenAI, Anthropic) to reduce local CPU load
* Ensure your Docker resource limits are appropriate

## Getting help

If you're still experiencing issues:

<CardGroup cols={2}>
  <Card title="GitHub Issues" icon="github" href="https://github.com/ItzCrazyKns/Perplexica/issues">
    Report bugs or search existing issues
  </Card>

  <Card title="Discord Community" icon="discord" href="https://discord.gg/EFwsmQDgAu">
    Get help from the community and developers
  </Card>

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

  <Card title="API Documentation" icon="code" href="https://github.com/ItzCrazyKns/Perplexica/tree/master/docs/API/SEARCH.md">
    API reference for developers
  </Card>
</CardGroup>

## Diagnostic information

When reporting issues, include:

```bash theme={null}
# Perplexica version
cat package.json | grep version

# Docker version
docker --version

# Container logs (last 50 lines)
docker logs --tail 50 perplexica

# Container status
docker ps -a | grep perplexica

# System information
uname -a
```