Troubleshooting Guide

Table of Contents

• Quick Fixes
• Installation Issues
• Performance Problems
• Display & Interface Issues
• File Access Problems
• Configuration Issues
• Security & Permission Errors
• Diagnostic Tools
• Getting Help

Quick Fixes

Most Common Issues (Try these first)

Indexer Not Loading

# Check PHP is working
echo "<?php phpinfo(); ?>" > test.php
# Access test.php in browser

# Check file permissions
chmod 644 index.php
ls -la index.php

Files Not Appearing

# Check configuration exists
ls -la .indexer_files/config.json

# Create basic configuration if missing
mkdir -p .indexer_files
cat > .indexer_files/config.json << 'EOF'
{
  "version": "1.0",
  "main": {
    "cache_type": "json",
    "local_icons": true
  },
  "exclusions": {
    "index_folders": true,
    "index_txt": true
  },
  "viewable_files": {
    "view_txt": true
  }
}
EOF

# Clear cache
rm -rf .indexer_files/index_cache/*

Performance Issues

{
  "main": {
    "cache_type": "sqlite"
  }
}

Icons Not Loading

Icons are now always local - check if .indexer_files/icons/ directory exists and contains icon files.

Installation Issues

Indexer Not Loading

Symptom: Blank page or "file not found"

Diagnostic steps:

1. Check PHP installation:

php --version
   which php

1. Test PHP processing:

<?php echo "PHP is working: " . phpversion(); ?>

1. Check web server error logs:

# Apache
   tail -f /var/log/apache2/error.log
   
   # Nginx  
   tail -f /var/log/nginx/error.log

1. Verify file permissions:

ls -la index.php
   # Should show: -rw-r--r-- (644)

Solutions:

• Install PHP if missing: apt-get install php
• Fix permissions: chmod 644 index.php
• Enable PHP in web server configuration
• Check DocumentRoot is correct

Configuration Directory Missing

Symptom: Error about .indexer_files directory or configuration

Solutions:

# Create configuration structure manually
mkdir -p .indexer_files/{zip_cache,index_cache,icons}
chmod -R 755 .indexer_files

# Create basic configuration
cat > .indexer_files/config.json << 'EOF'
{
  "version": "1.0",
  "main": {
    "cache_type": "sqlite",
    "local_icons": true,
    "disable_file_downloads": false,
    "disable_folder_downloads": false,
    "index_hidden": false,
    "deny_list": "",
    "allow_list": ""
  },
  "exclusions": {
    "index_folders": true,
    "index_txt": true
  },
  "viewable_files": {
    "view_txt": true
  }
}
EOF

chmod 644 .indexer_files/config.json

Missing PHP Extensions

Symptom: Fatal errors about missing functions

Check extensions:

php -m | grep -E "(sqlite|zip|json)"

Install missing extensions:

# Ubuntu/Debian
sudo apt-get install php-sqlite3 php-zip php-curl

# CentOS/RHEL
sudo yum install php-sqlite3 php-zip php-curl

# Check loaded extensions
php -i | grep -E "(sqlite|zip)"

Performance Problems

Slow Directory Loading

Symptom: Long loading times for file listings

Solutions:

1. Enable SQLite caching:

{
     "main": {
       "cache_type": "sqlite"
     }
   }

1. Verify SQLite is available:

php -m | grep sqlite3

1. Clear existing cache:

rm -rf .indexer_files/index_cache/*

1. Increase PHP limits:

; In php.ini
   memory_limit = 256M
   max_execution_time = 60

Memory Limit Errors

Symptom: "Fatal error: Allowed memory size exhausted"

Solutions:

; Increase in php.ini
memory_limit = 512M
max_execution_time = 300

; Or for specific directory in .htaccess
php_value memory_limit 512M
php_value max_execution_time 300

Timeout Errors

Symptom: "Maximum execution time exceeded"

Solutions:

; In php.ini
max_execution_time = 300
set_time_limit = 300

; For large directories
max_input_time = 300

Display & Interface Issues

Icons Not Loading

Symptom: No icons or generic icons only

Solutions:

1. Check icon directory exists:

ls -la .indexer_files/icons/

1. Check configuration:

{
     "main": {
       "icon_type": "default",
       "local_icons": true
     }
   }

1. Create basic icons manually:

mkdir -p .indexer_files/icons
   # Add icon files as needed for your file types

1. Use emoji fallback:

{
     "main": {
       "icon_type": "emoji"
     }
   }

Interface Display Problems

Symptom: Broken layout, missing styles

Solutions:

1. Check configuration exists:

ls -la .indexer_files/config.json

1. Clear browser cache:

Ctrl+Shift+Delete (Windows)
   Cmd+Shift+Delete (Mac)

1. Test with different browser:

• Chrome, Firefox, Safari, Edge
• Disable browser extensions

1. Create minimal configuration:

{
     "version": "1.0",
     "main": {
       "cache_type": "json",
       "icon_type": "emoji"
     }
   }

Mobile Display Issues

Symptom: Poor mobile interface, unresponsive design

Solutions:

1. Update browser to latest version
2. Clear mobile browser cache
3. Try different mobile browser (Chrome, Firefox, Safari)
4. Test on different mobile device

File Access Problems

Files Not Appearing

Symptom: Expected files don't show in listings

Diagnostic checklist:

1. Check file permissions:

ls -la filename.ext
   # Should be readable: -rw-r--r--

1. Verify extension configuration:

{
     "exclusions": {
       "index_php": true  // true = show, false = hide
     }
   }

1. Check deny list:

{
     "main": {
       "deny_list": "*.php, admin, logs"
     }
   }

1. Hidden files:

{
     "main": {
       "index_hidden": true  // Show files starting with "."
     }
   }

Solutions:

• Fix file permissions: chmod 644 filename.ext
• Update configuration to include file type
• Remove from deny list or add to allow list
• Enable hidden file indexing if needed

Cannot Access Directories

Symptom: Folders appear but clicking produces errors

Solutions:

1. Check directory permissions:

ls -ld /path/to/folder
   # Should have execute permission: drwxr-xr-x
   chmod 755 folder/

1. Verify folder indexing:

{
     "exclusions": {
       "index_folders": true
     }
   }

1. Check path security:

• Ensure no ../ or ./ in path
• Verify no special characters causing issues

Download Problems

Symptom: Download buttons missing or not working

Solutions:

1. Check download settings:

{
     "main": {
       "disable_file_downloads": false,
       "disable_folder_downloads": false
     }
   }

1. Verify ZIP extension:

php -m | grep zip
   # If missing: apt-get install php-zip

1. Check disk space:

df -h .indexer_files/zip_cache/

1. Test with small file first

Large File Download Issues

Solutions:

; In php.ini
max_execution_time = 600
memory_limit = 1024M
post_max_size = 2G
upload_max_filesize = 2G

; Check current limits
php -i | grep -E "(max_execution_time|memory_limit|post_max_size)"

Configuration Issues

Configuration Not Found

Symptom: Default behavior, no configuration applied

Cause: Configuration file missing or not readable. Solutions:

1. Check if configuration exists:

ls -la .indexer_files/config.json

1. Create basic configuration:

mkdir -p .indexer_files
   cat > .indexer_files/config.json << 'EOF'
   {
     "version": "1.0",
     "main": {
       "cache_type": "sqlite",
       "local_icons": true
     },
     "exclusions": {
       "index_folders": true,
       "index_txt": true
     },
     "viewable_files": {
       "view_txt": true
     }
   }
   EOF
   chmod 644 .indexer_files/config.json

Configuration Not Taking Effect

Symptom: Changes to config.json don't work

Solutions:

1. Validate JSON syntax:

python -m json.tool .indexer_files/config.json

1. Clear cache:

rm -rf .indexer_files/index_cache/*

1. Check file permissions:

chmod 644 .indexer_files/config.json

1. Restart web server:

sudo systemctl restart apache2
   # or
   sudo systemctl restart nginx

Invalid Configuration

Symptom: Indexer uses defaults despite config file

Solutions:

# Check for JSON syntax errors
python -m json.tool .indexer_files/config.json

# Fix common JSON issues:
# - Missing commas
# - Trailing commas
# - Unquoted keys
# - Invalid values

# Create minimal working config
cat > .indexer_files/config.json << 'EOF'
{
  "version": "1.0",
  "main": {
    "cache_type": "json"
  },
  "exclusions": {
    "index_folders": true
  },
  "viewable_files": {
    "view_txt": true
  }
}
EOF

Security & Permission Errors

Permission Denied Errors

Symptom: Various "Permission denied" errors

Solutions:

1. Fix web server permissions:

# For Apache (www-data)
   chown -R www-data:www-data .indexer_files/
   
   # For Nginx
   chown -R nginx:nginx .indexer_files/

1. Set correct file modes:

find .indexer_files/ -type f -exec chmod 644 {} \;
   find .indexer_files/ -type d -exec chmod 755 {} \;

1. Check SELinux (if applicable):

# Check status
   sestatus
   
   # Set correct context
   restorecon -R .indexer_files/

Access Denied Errors

Symptom: "Access denied - path traversal detected"

Cause: Security system detecting potential attacks Solutions:

1. Check URL for invalid characters:

• Remove ../ or ./ from URLs
• Avoid encoded traversal attempts

1. Use clean navigation:

• Navigate through interface instead of editing URLs
• Use breadcrumbs for navigation

1. Check for symlink issues:

ls -la | grep "^l"  # Find symlinks

ZIP Creation Failures

Symptom: "Failed to create zip file"

Solutions:

1. Check ZIP extension:

php -m | grep zip
   # Install if missing: apt-get install php-zip

1. Verify disk space:

df -h .indexer_files/

1. Check temp directory permissions:

chmod 755 .indexer_files/zip_cache/
   ls -ld .indexer_files/zip_cache/

1. Test ZIP functionality:

<?php
   $zip = new ZipArchive();
   $result = $zip->open('/tmp/test.zip', ZipArchive::CREATE);
   echo "ZIP test result: " . $result . "\n";
   ?>

Diagnostic Tools

System Information Collection

Run this diagnostic script:

#!/bin/bash
echo "=== 5q12's Indexer Diagnostics ==="
echo "Date: $(date)"
echo ""

echo "=== System Information ==="
echo "OS: $(uname -a)"
echo "PHP Version: $(php --version | head -1)"
echo "Web Server: $(ps aux | grep -E '(apache|nginx|httpd)' | head -1)"
echo ""

echo "=== PHP Extensions ==="
php -m | grep -E "(sqlite|zip|json|curl|gd)"
echo ""

echo "=== File Permissions ==="
ls -la index.php .indexer_files/ 2>/dev/null || echo "Configuration directory missing"
echo ""

echo "=== Disk Space ==="
df -h .
echo ""

echo "=== Configuration ==="
if [ -f .indexer_files/config.json ]; then
    echo "Config exists: YES"
    python -m json.tool .indexer_files/config.json > /dev/null 2>&1
    if [ $? -eq 0 ]; then
        echo "Config valid: YES"
    else
        echo "Config valid: NO - JSON syntax error"
    fi
else
    echo "Config exists: NO"
fi
echo ""

echo "=== Cache Status ==="
if [ -d .indexer_files/index_cache ]; then
    echo "Cache dir exists: YES"
    echo "Cache files: $(find .indexer_files/index_cache -type f 2>/dev/null | wc -l)"
else
    echo "Cache dir exists: NO"
fi
echo ""

echo "=== Error Logs (last 10 lines) ==="
if [ -f /var/log/apache2/error.log ]; then
    tail -10 /var/log/apache2/error.log
elif [ -f /var/log/nginx/error.log ]; then
    tail -10 /var/log/nginx/error.log
else
    echo "No standard error logs found"
fi

Configuration Validator

Create config validator:

<?php
function validateIndexerConfig($configFile = '.indexer_files/config.json') {
    echo "=== Configuration Validator ===\n";
    
    if (!file_exists($configFile)) {
        echo "ERROR: Configuration file not found\n";
        echo "Create configuration with:\n";
        echo "mkdir -p .indexer_files\n";
        echo 'cat > .indexer_files/config.json << \'EOF\'' . "\n";
        echo '{"version":"1.0","main":{"cache_type":"json"},"exclusions":{"index_folders":true},"viewable_files":{"view_txt":true}}' . "\n";
        echo "EOF\n";
        return false;
    }
    
    $content = file_get_contents($configFile);
    $config = json_decode($content, true);
    
    if (json_last_error() !== JSON_ERROR_NONE) {
        echo "ERROR: Invalid JSON - " . json_last_error_msg() . "\n";
        return false;
    }
    
    echo "✓ JSON syntax valid\n";
    
    // Check required sections
    $required = ['version', 'main', 'exclusions', 'viewable_files'];
    foreach ($required as $section) {
        if (!isset($config[$section])) {
            echo "WARNING: Missing section '$section'\n";
        } else {
            echo "✓ Section '$section' present\n";
        }
    }
    
    // Check main settings
    if (isset($config['main'])) {
        $mainDefaults = [
            'cache_type' => 'json',
            'local_icons' => true,
            'disable_file_downloads' => false
        ];
        
        foreach ($mainDefaults as $key => $default) {
            if (!isset($config['main'][$key])) {
                echo "INFO: Using default for main.$key = $default\n";
            } else {
                echo "✓ Setting main.$key = " . json_encode($config['main'][$key]) . "\n";
            }
        }
    }
    
    echo "Configuration validation complete\n";
    return true;
}

validateIndexerConfig();
?>

Performance Test

Test directory loading performance:

<?php
function testPerformance($directory = '.') {
    $start = microtime(true);
    
    $files = scandir($directory);
    $count = 0;
    
    foreach ($files as $file) {
        if ($file === '.' || $file === '..') continue;
        $count++;
        $filePath = $directory . '/' . $file;
        $size = is_dir($filePath) ? 0 : filesize($filePath);
        $modified = filemtime($filePath);
    }
    
    $end = microtime(true);
    $time = round(($end - $start) * 1000, 2);
    
    echo "Performance Test Results:\n";
    echo "Directory: $directory\n";
    echo "Files processed: $count\n";
    echo "Time taken: {$time}ms\n";
    echo "Average per file: " . round($time / max($count, 1), 2) . "ms\n";
}

testPerformance();
?>

Getting Help

Information to Collect

When seeking help, provide:

1. Environment Details:

uname -a
   php --version
   apache2 -v  # or nginx -v

1. Error Information:

• Exact error messages
• Steps to reproduce
• When issue started
• Recent changes

1. Configuration:

cat .indexer_files/config.json | python -m json.tool
   ls -la .indexer_files/

1. Logs:

tail -50 /var/log/apache2/error.log
   tail -20 .indexer_files/debug.log  # if exists

Common Solutions Summary

Problem	Quick Fix
Not loading	Check PHP installation and permissions
Files missing	Create configuration file manually
Slow performance	Enable SQLite caching
Icons missing	Set icon_type to "emoji" or create local icons
Downloads fail	Check ZIP extension and permissions
Config ignored	Validate JSON syntax and clear cache
Permission errors	Fix file ownership and permissions
Configuration missing	Create .indexer_files/config.json manually

Configuration Template

Minimal working configuration:

{
  "version": "1.0",
  "main": {
    "cache_type": "sqlite",
    "local_icons": true,
    "disable_file_downloads": false,
    "disable_folder_downloads": false,
    "index_hidden": false,
    "deny_list": "",
    "allow_list": ""
  },
  "exclusions": {
    "index_folders": true,
    "index_txt": true,
    "index_php": true,
    "index_js": true,
    "index_html": true,
    "index_json": true,
    "index_png": true,
    "index_jpg": true,
    "index_pdf": true,
    "index_zip": true
  },
  "viewable_files": {
    "view_txt": true,
    "view_php": true,
    "view_js": true,
    "view_html": true,
    "view_json": true,
    "view_png": true,
    "view_jpg": true,
    "view_pdf": true
  }
}

Recovery Procedures

Complete reset if all else fails:

# Backup current state
cp -r .indexer_files .indexer_files.backup 2>/dev/null || echo "No existing config"

# Remove configuration
rm -rf .indexer_files

# Create fresh configuration
mkdir -p .indexer_files/{zip_cache,index_cache,icons}
# Copy the minimal configuration template above to .indexer_files/config.json
chmod 644 .indexer_files/config.json
chmod -R 755 .indexer_files/

# Access indexer to test
curl -I https://yourdomain.com/path/to/indexer/

Support Resources

1. Repository - Check for updates and documentation at https://ccls.icu/src/repositories/5q12-indexer/
2. Documentation - Review related guides:

• Installation Guide - Setup issues
• Configuration Guide - Settings problems
• Security Guide - Permission and access issues

1. System Administrator - Consider professional help for complex server issues

This troubleshooting guide provides systematic approaches to diagnose and resolve the most common issues with 5q12's Indexer in its current offline-only configuration.