Troubleshooting

This guide helps you resolve common issues when running HabitTrove.

⚠️ Data Directory Errors

HabitTrove performs startup checks to ensure the data directory is accessible and functional. You may encounter different error messages depending on the specific issue:

Your data is stored in the mounted data directory (e.g. ./data) on your host system, and mounted to /app/data inside the container.

Note that the owner of the data directory should be the same as the container user (uid 1001).

Error 1: Directory Missing or Inaccessible

Error Message:

Data directory 'data' does not exist or is not accessible. Check volume mounts and permissions.

Root Cause: The data directory doesn't exist on your host system or the container cannot access it due to volume mounting issues.

Solution:

# Create the data directory
mkdir -p ./data

# Set correct ownership for container user (uid 1001)
sudo chown -R 1001:1001 ./data

# then refresh the browser

Error 2: Path Exists But Is Not a Directory

Error Message:

Path 'data' exists but is not a directory. Please ensure the data directory is properly configured.

Root Cause: A file named data exists where the directory should be, or the path points to a non-directory object.

Solution:

# Remove the file and create proper directory
rm ./data
mkdir -p ./data
sudo chown -R 1001:1001 ./data

# then refresh the browser

Error 3: Insufficient Permissions

Error Message:

Insufficient read/write permissions for data directory 'data'. Check file permissions and ownership.

Root Cause: The data directory exists but the container user (uid 1001) cannot read from or write to it.

Solution:

# Fix ownership and permissions
sudo chown -R 1001:1001 ./data
chmod 755 ./data

# then refresh the browser

Error 4: Data Integrity Issues

Error Message:

Data integrity check failed in 'data'. File system may be corrupted or have inconsistent behavior.

Root Cause: This rare error indicates the file system has corruption or inconsistent read/write behavior. This could be caused by:

• Disk hardware issues
• File system corruption
• Network storage connectivity problems
• Insufficient disk space
• Container/host file system inconsistencies

Please try to write files to the data directory manually to verify if directory is working correctly.