> ## Documentation Index
> Fetch the complete documentation index at: https://critiqor-71f5274a.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting Critiqor Installation & Runtime Issues

> Fix common Critiqor problems — installation failures, command not found, empty sessions, backend config errors, and dashboard display issues.

This page covers the most common issues you may encounter when installing, configuring, or running Critiqor — and how to resolve them quickly.

<AccordionGroup>
  <Accordion title="pip install critiqor fails">
    Check that you're running **Python 3.10 or later**:

    ```bash theme={null}
    python --version
    ```

    Update pip before retrying:

    ```bash theme={null}
    pip install --upgrade pip
    pip install critiqor
    ```

    If the error persists, install inside a virtual environment to avoid system-level conflicts:

    ```bash theme={null}
    python -m venv .venv
    source .venv/bin/activate   # macOS / Linux
    .venv\Scripts\activate      # Windows
    pip install critiqor
    ```
  </Accordion>

  <Accordion title="SSL errors during install">
    If your network or corporate proxy causes SSL verification failures, pass trusted hosts explicitly:

    ```bash theme={null}
    pip install critiqor \
      --trusted-host pypi.org \
      --trusted-host files.pythonhosted.org
    ```

    This bypasses SSL certificate verification for the PyPI download only. For a long-term fix, talk to your network administrator about adding the relevant CA certificates to your system trust store.
  </Accordion>

  <Accordion title="critiqor: command not found">
    After installation, the `critiqor` CLI entry point may not be on your `PATH`. Try invoking it via Python directly as a fallback:

    ```bash theme={null}
    python -m critiqor
    ```

    **To fix `PATH` permanently:**

    * **macOS / Linux** — add your Python `bin` directory to your shell profile (e.g. `~/.bashrc` or `~/.zshrc`):
      ```bash theme={null}
      export PATH="$HOME/.local/bin:$PATH"
      ```
    * **Windows** — add the Python `Scripts` directory (e.g. `C:\Users\<you>\AppData\Local\Programs\Python\Python3x\Scripts`) to your system `PATH` via System Properties → Environment Variables.

    If you're using a **virtual environment**, make sure it's activated before running `critiqor`:

    ```bash theme={null}
    source .venv/bin/activate   # macOS / Linux
    .venv\Scripts\activate      # Windows
    ```
  </Accordion>

  <Accordion title="Dashboard doesn't open after critiqor finalize">
    If your browser doesn't open automatically:

    1. Check that no firewall or security tool is blocking localhost connections.
    2. Try specifying a host and port explicitly:
       ```bash theme={null}
       critiqor dashboard --host 127.0.0.1 --port 8080
       ```
    3. Copy the URL printed in your terminal and open it manually in your browser.

    If none of these work, verify that the port isn't already in use by another process:

    ```bash theme={null}
    lsof -i :8080   # macOS / Linux
    netstat -ano | findstr :8080   # Windows
    ```
  </Accordion>

  <Accordion title="Dashboard opens but shows no data">
    The dashboard requires a completed run to display a report. Make sure you ran `critiqor finalize` after your observation session — not just `critiqor monitor`.

    The typical workflow is:

    ```bash theme={null}
    critiqor monitor openclaw   # start observing
    # ... use your agent ...
    critiqor finalize           # end session and generate report
    critiqor dashboard          # view the report
    ```

    If you open the dashboard before finalizing, it has nothing to display yet.
  </Accordion>

  <Accordion title="Observation session appears empty">
    The observation window starts **when you run `critiqor monitor openclaw`**, not before. If you started your agent before running the monitor command, those interactions fall outside the session and are not captured.

    Always follow this order:

    1. Run `critiqor monitor openclaw` first.
    2. Then start using your agent.
    3. Then run `critiqor finalize` when done.
  </Accordion>

  <Accordion title="No events captured during session">
    If your session completed but no events were recorded:

    * Confirm that OpenClaw was launched **through** the Critiqor monitor command, not independently in a separate terminal.
    * Verify that you actively interacted with your agent during the observation window.
    * Check that OpenClaw is installed and available in your `PATH`:
      ```bash theme={null}
      which openclaw     # macOS / Linux
      where openclaw     # Windows
      ```

    If OpenClaw is not found, install it and re-run `critiqor monitor openclaw`.
  </Accordion>

  <Accordion title="Permission denied writing run artifacts">
    Critiqor writes run artifacts to your current working directory. If that directory is not writable, you'll see a permission error.

    * Run Critiqor from your home directory or a project folder where you have write access.
    * On **macOS / Linux**, fix permissions on your project directory if needed:
      ```bash theme={null}
      chmod 755 /path/to/your/project
      ```
    * On **Windows**, make sure you're not running from a read-only or system-protected path (e.g. `C:\Program Files`).
  </Accordion>

  <Accordion title="critiqor finalize prints a backend configuration error">
    Critiqor connects to a backend to generate reliability reports. If the backend is not configured, finalization will fail.

    Set the required environment variables before running `critiqor finalize`:

    ```bash theme={null}
    export CRITIQOR_BACKEND_URL="https://your-backend-url"
    export CRITIQOR_API_KEY="your-api-key"    # if required
    ```

    On **Windows (PowerShell)**:

    ```powershell theme={null}
    $env:CRITIQOR_BACKEND_URL = "https://your-backend-url"
    $env:CRITIQOR_API_KEY = "your-api-key"
    ```

    If you don't have a backend URL or API key, contact [Critiqor support](https://github.com/web3curtis/Critiqor) to get your credentials.
  </Accordion>

  <Accordion title="How do I update Critiqor?">
    Run:

    ```bash theme={null}
    pip install --upgrade critiqor
    ```

    Verify the installed version after upgrading:

    ```bash theme={null}
    pip show critiqor
    ```
  </Accordion>

  <Accordion title="OpenClaw is not launching">
    Critiqor starts OpenClaw automatically when you run `critiqor monitor openclaw`. If OpenClaw does not launch:

    1. Confirm that OpenClaw is installed on your system.
    2. Confirm that the `openclaw` binary is available in your `PATH`:
       ```bash theme={null}
       which openclaw     # macOS / Linux
       where openclaw     # Windows
       ```
    3. If it's not found, install OpenClaw and try again.
  </Accordion>
</AccordionGroup>

<Note>
  If you're still stuck, open a GitHub issue at [github.com/web3curtis/Critiqor](https://github.com/web3curtis/Critiqor) and include:

  * Your Critiqor version (`pip show critiqor`)
  * Your Python version (`python --version`)
  * The exact command you ran
  * What you expected to happen
  * What actually happened (include any error output)
</Note>