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

# Troubleshooting

> Solutions to common Memory Monitor issues and errors

This guide covers common issues you may encounter when using Memory Monitor and how to resolve them.

## Common Errors

<AccordionGroup>
  <Accordion title="PermissionError: [Errno 13] Permission denied">
    ### Problem

    Memory Monitor cannot read certain process information from `/proc/[pid]/status` due to insufficient permissions.

    ```
    PermissionError: [Errno 13] Permission denied: '/proc/1234/status'
    ```

    ### Why It Happens

    The Linux kernel restricts access to process information for security reasons. Processes owned by other users (especially root) cannot be read without elevated privileges.

    Memory Monitor is designed to **silently skip** processes it cannot access, so you'll still get results for processes you have permission to read.

    ### Solutions

    <Tip>
      **For most users:** No action needed. Memory Monitor will analyze all processes you have permission to read and still identify the highest memory consumer among them.
    </Tip>

    **If you need complete system visibility:**

    ```bash theme={null}
    # Run with sudo to access all processes
    sudo python3 main.py
    ```

    <Warning>
      Only use `sudo` if you need to monitor system processes or processes owned by other users. For monitoring your own applications, regular permissions are sufficient.
    </Warning>

    ### Code Behavior

    Memory Monitor handles this gracefully in `process_analyzer.py:25-26`:

    ```python theme={null}
    except PermissionError:
        continue  # Skip processes we can't access
    ```
  </Accordion>

  <Accordion title="FileNotFoundError: [Errno 2] No such file or directory">
    ### Problem

    A process terminated between when Memory Monitor listed it and when it tried to read its status file.

    ```
    FileNotFoundError: [Errno 2] No such file or directory: '/proc/5678/status'
    ```

    ### Why It Happens

    Processes can start and stop rapidly on a busy system. The `/proc/[pid]/` directory disappears immediately when a process exits.

    Memory Monitor handles this automatically by skipping terminated processes.

    ### Solution

    <Note>
      **No action required.** This is normal behavior and handled gracefully by the code in `process_analyzer.py:23-24`:

      ```python theme={null}
      except FileNotFoundError:
          continue  # Process terminated, skip it
      ```
    </Note>

    If you see this error displayed (which shouldn't happen with the current code), it means the exception handling is working correctly. The tool will continue scanning other processes.
  </Accordion>

  <Accordion title="No output appears or empty results">
    ### Problem

    Memory Monitor runs but shows no memory statistics or shows zeros for all values.

    ### Possible Causes

    **1. Running on non-Linux system**

    Memory Monitor requires Linux's `/proc` filesystem and will not work on:

    * Windows
    * macOS
    * BSD systems (without Linux compatibility layer)

    <Warning>
      Memory Monitor is designed exclusively for Linux systems. It reads from `/proc/meminfo` and `/proc/[pid]/status`, which are Linux-specific kernel interfaces.
    </Warning>

    **Solution:** Run Memory Monitor on a Linux machine or use a Linux VM/container.

    **2. /proc filesystem not mounted**

    In rare cases (containers, chroots), `/proc` may not be mounted.

    Check if `/proc` is available:

    ```bash theme={null}
    ls /proc/meminfo
    ```

    If missing, mount it:

    ```bash theme={null}
    sudo mount -t proc proc /proc
    ```

    **3. No processes are readable**

    If running in a restricted environment where all processes are owned by other users, you may need elevated permissions (see PermissionError section above).
  </Accordion>

  <Accordion title="OSError or IOError when reading /proc files">
    ### Problem

    Unexpected I/O errors when accessing `/proc` filesystem.

    ### Possible Causes

    * Corrupted or unusual `/proc` filesystem state
    * Running in a container with restricted access
    * System under extreme load or out of memory

    ### Solutions

    1. **Verify `/proc` is accessible:**
       ```bash theme={null}
       cat /proc/meminfo
       ```

    2. **Check system resources:**
       ```bash theme={null}
       df -h
       free -h
       ```

    3. **Restart in a clean environment:**
       * Exit and restart your terminal
       * If in a container, restart the container

    4. **Check system logs:**
       ```bash theme={null}
       sudo dmesg | tail -50
       ```
       Look for kernel errors related to memory or processes.
  </Accordion>
</AccordionGroup>

## Platform Compatibility

<Warning>
  **Linux Only:** Memory Monitor requires a Linux operating system with a standard `/proc` filesystem.
</Warning>

### Supported

* Ubuntu / Debian
* Red Hat / CentOS / Fedora
* Arch Linux
* Alpine Linux (in containers)
* Any Linux distribution with `/proc` filesystem

### Not Supported

* Windows (no `/proc` filesystem)
* macOS (uses different process information system)
* BSD systems (use different `/proc` structure)

### Running in Containers

Memory Monitor works in Docker and other containers, but:

<Note>
  **Container considerations:**

  * You'll only see processes running inside the container
  * Memory statistics reflect the container's view (may be limited by cgroups)
  * Some containers run as non-root and may have limited `/proc` access

  To see host processes, you need to run on the host system, not in a container.
</Note>

## Python Version Issues

### Type Hint Compatibility

The code uses modern Python type hints including:

```python theme={null}
def InformationMemory() -> str | None:
def ListDirectory() -> tuple[str, int] | None:
```

<Warning>
  **Minimum Python version: 3.10+**

  The `|` union syntax and lowercase generic types (`list`, `tuple`) require Python 3.10 or later.
</Warning>

### If You See Type Errors

```
TypeError: unsupported operand type(s) for |: 'type' and 'type'
```

or

```
TypeError: 'type' object is not subscriptable
```

**Solution:**

1. **Check your Python version:**
   ```bash theme={null}
   python3 --version
   ```

2. **Upgrade to Python 3.10 or later:**
   ```bash theme={null}
   # Ubuntu/Debian
   sudo apt update
   sudo apt install python3.10

   # Fedora
   sudo dnf install python3.10
   ```

3. **Or modify the code for older Python:**

   Replace type hints with compatible syntax:

   ```python theme={null}
    from typing import Optional, List
    
    def InformationMemory() -> Optional[str]:
    def ListDirectory() -> Optional[List[str]]:
   ```

## Installation Issues

<AccordionGroup>
  <Accordion title="Module not found errors">
    ### Problem

    ```
    ModuleNotFoundError: No module named 'memory_info'
    ```

    ### Solution

    Ensure all files are in the same directory:

    ```bash theme={null}
    ls -l
    # Should show:
    # main.py
    # memory_info.py
    # process_analyzer.py
    ```

    Run from the directory containing the files:

    ```bash theme={null}
    cd /path/to/memory-monitor
    python3 main.py
    ```
  </Accordion>

  <Accordion title="Python command not found">
    ### Problem

    ```
    bash: python3: command not found
    ```

    ### Solution

    Install Python 3:

    ```bash theme={null}
    # Ubuntu/Debian
    sudo apt update
    sudo apt install python3

    # Fedora
    sudo dnf install python3

    # Arch
    sudo pacman -S python
    ```
  </Accordion>
</AccordionGroup>

## Unexpected Output Issues

<AccordionGroup>
  <Accordion title="All memory values show as 0">
    ### Problem

    ```
    Memoria Total: 0 kB
    Memoria Libre: 0 kB
    Buffers: 0 kB
    Cached: 0 kB
    Memoria Usada: 0 kB
    ```

    ### Diagnosis

    Check if `/proc/meminfo` is readable:

    ```bash theme={null}
    cat /proc/meminfo | head -10
    ```

    ### Solutions

    * Ensure you're on a Linux system
    * Verify `/proc` is mounted (see "No output appears" above)
    * Check file permissions on `/proc/meminfo`
  </Accordion>

  <Accordion title="VmRSS shows 0 kB for top process">
    ### Problem

    ```
    El proceso con mayor VmRSS es
     Name: systemd
     PID: 1
     VmRSS: 0 kB
    ```

    ### Why It Happens

    This can occur when:

    1. No processes have VmRSS information available
    2. All readable processes terminated during the scan
    3. All processes you can access have no resident memory (very unlikely)

    ### Solution

    Run with `sudo` to ensure you can read process information:

    ```bash theme={null}
    sudo python3 main.py
    ```
  </Accordion>
</AccordionGroup>

## Getting Help

<Tip>
  **Still having issues?**

  1. **Verify your environment:**
     * Confirm you're on Linux: `uname -s` (should output "Linux")
     * Check Python version: `python3 --version` (should be 3.10+)
     * Test `/proc` access: `cat /proc/meminfo`

  2. **Check system logs:**
     ```bash theme={null}
     sudo dmesg | tail -50
     journalctl -xe | tail -50
     ```

  3. **Run with verbose output:**
     Add debug print statements to see where the issue occurs
</Tip>

## Next Steps

* Learn how to interpret output: [Understanding Output](/guides/understanding-output)
* Review installation steps: [Quickstart](/quickstart)
* Understand memory metrics: [Understanding Output - Memory Statistics](/guides/understanding-output#memory-statistics-section)