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

# Troubleshooting

> Solutions to common Aikeedo installation, configuration, and runtime issues including database errors, asset loading problems, and model configuration.

## Overview

This guide provides solutions to common issues users encounter when installing, configuring, and running Aikeedo. Issues are organized by category for easy navigation.

## Before You Begin

Before troubleshooting, verify that:

1. Your server meets all [server requirements](/overview/server-requirements)
2. You have the latest version of Aikeedo files
3. You've followed the [installation guide](/setup/installation) carefully
4. You've completed [initial setup](/setup/initial-setup) steps

## Quick Navigation

Find your issue and click to jump to the solution:

### Installation Issues

* [Assets Not Loading (CSS, JS, Images)](#assets-not-loading)
* [404 or 403 Errors During Installation](#404-or-403-errors-during-installation)
* [Database Connection Issues](#database-connection-issues)
* [500 Internal Server Error During Installation](#500-internal-server-error-during-installation)
* [Installation Wizard Not Loading](#installation-wizard-not-loading)

### Configuration Issues

* ["Does Not Allow the Value" Error](#"does-not-allow-the-value"-error)
* [Cannot Select Models or Send Prompts](#cannot-select-models-or-send-prompts)
* [500 Error on Image Generator or Video Generator](#500-error-on-image-generator-or-video-generator)
* [Save Button Does Nothing](#save-button-does-nothing)

### Database Issues

* [MySQL Server Has Gone Away](#mysql-server-has-gone-away)

### Feature-Specific Issues

* [Auto-Generated Titles Don't Match Content Language](#auto-generated-titles-don't-match-content-language)
* [Uploaded Files Return 404 Not Found Errors](#uploaded-files-return-404-not-found-errors)
* [Generated Images/Videos Not Loading](#generated-images%2Fvideos-not-loading)

***

## Installation Issues

### Assets Not Loading

**Symptoms:**

* Installation page appears without styling
* Images, CSS, and JavaScript files fail to load
* Browser shows 404 errors for asset files

**Cause:**
The domain is not correctly pointing to the `public` directory.

**Solution:**

<Steps>
  <Step title="Verify Document Root">
    Ensure your domain points to the `public` directory within your Aikeedo installation:

    ```
    /path/to/aikeedo/public
    ```

    Not to the root Aikeedo directory.
  </Step>

  <Step title="Test Redirection">
    Visit your domain (e.g., `https://yourdomain.com`). You should be automatically redirected to `https://yourdomain.com/install`.

    <Check>
      If the redirect works, your domain is configured correctly.
    </Check>
  </Step>

  <Step title="cPanel Users">
    If you're using cPanel and cannot change the document root for your main domain, follow the dedicated [cPanel Installation Guide](/setup/installation/cpanel).

    <Note>
      The cPanel installation process differs from the standard installation due to control panel limitations.
    </Note>
  </Step>
</Steps>

**Related Documentation:**

* [Installation Guide](/setup/installation)
* [cPanel Installation](/setup/installation/cpanel)

***

### 404 or 403 Errors During Installation

**Symptoms:**

* 404 error when accessing `/install`
* 403 Forbidden error on home page
* Installation wizard not accessible

**Cause:**
Domain document root not pointing to the `public` directory, missing files, incorrect permissions, or web server configuration issues preventing proper request routing.

**Solution:**

<Steps>
  <Step title="Verify Document Root Configuration">
    Ensure your domain's document root points to the `public` folder:

    **For cPanel:**

    * Main domain: Points to `public_html` by default (this is correct)
    * Ensure Aikeedo's `public` folder contents are copied to `public_html`
    * Add-on domains/subdomains: Update document root in cPanel to point to the `public` folder

    **For VPS/Dedicated:**

    * Set document root to `/path/to/aikeedo/public`

    <Tip>
      Accessing your domain should automatically redirect you to `/install` if the document root is correctly configured.
    </Tip>
  </Step>

  <Step title="Configure Web Server">
    Configure your web server to serve PHP applications and rewrite all requests to `/public/index.php`:

    <Tabs>
      <Tab title="Nginx">
        Ensure your server block is configured correctly:

        ```nginx /etc/nginx/sites-available/aikeedo theme={null}
        server {
            listen 80;
            listen [::]:80;
            server_name yourdomain.com www.yourdomain.com;
            root /path/to/aikeedo/public;
            
            # Add index.php to the list
            index index.php index.html index.htm index.nginx-debian.html;
            
            # Increase the maximum upload size
            client_max_body_size 256M;
            
            location / {
                # First attempt to serve request as file, then
                # as directory, then fall back to index.php
                try_files $uri $uri/ /index.php$is_args$query_string;
            }
            
            # Pass PHP scripts to FastCGI server
            location ~ \.php$ {
                include snippets/fastcgi-php.conf;
                
                # Fix for PHP files downloading instead of execute
                fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
                fastcgi_param DOCUMENT_ROOT $realpath_root;
                
                # With php-fpm (or other unix sockets):
                fastcgi_pass unix:/run/php/php-fpm.sock;
                # With php-cgi (or other tcp sockets):
                # fastcgi_pass 127.0.0.1:9000;
                
                fastcgi_connect_timeout 300s;
                fastcgi_send_timeout 300s;
                fastcgi_read_timeout 300s;
            }
            
            # Deny access to .htaccess files, if Apache's document root
            # concurs with nginx's one
            location ~ /\.ht {
                deny all;
            }
        }
        ```

        <Note>
          After configuring, test your Nginx configuration: `sudo nginx -t` and reload: `sudo systemctl reload nginx`

          Adjust the `fastcgi_pass` socket path to match your PHP-FPM configuration. Common locations:

          * `/run/php/php-fpm.sock` (generic)
          * `/run/php/php8.2-fpm.sock` (version-specific)
          * `/var/run/php/php8.2-fpm.sock` (alternative path)
        </Note>
      </Tab>

      <Tab title="Apache">
        Ensure your virtual host is configured correctly with proper rewrite rules:

        ```apache /etc/apache2/sites-available/aikeedo.conf theme={null}
        <VirtualHost *:80>
            ServerName yourdomain.com
            ServerAlias www.yourdomain.com
            DocumentRoot /path/to/aikeedo/public

            <Directory /path/to/aikeedo/public>
                Options -Indexes +FollowSymLinks
                AllowOverride All
                Require all granted
            </Directory>
        </VirtualHost>
        ```

        <Note>
          Ensure `mod_rewrite` is enabled: `sudo a2enmod rewrite` and reload Apache: `sudo systemctl reload apache2`
        </Note>
      </Tab>
    </Tabs>

    <Warning>
      The server configurations provided above are minimal samples. Consult with your server administrator for the correct configuration for your specific server environment, especially if you're using load balancers, reverse proxies, or have specific security requirements.
    </Warning>
  </Step>

  <Step title="Verify .htaccess File (Apache)">
    If you're using Apache, ensure the `.htaccess` file is present in the `public` directory. Aikeedo includes this file by default with the correct rewrite rules.

    <Note>
      Hidden files may not be visible by default. Enable "Show hidden files" in your FTP client or file manager if you need to verify the file exists.
    </Note>
  </Step>

  <Step title="Check File Extraction">
    Verify all Aikeedo files are extracted correctly and the `public` directory exists with all necessary files.
  </Step>

  <Step title="Set File Permissions">
    Ensure the web server has appropriate permissions:

    ```bash theme={null}
    # Set directory permissions
    find /path/to/aikeedo -type d -exec chmod 755 {} \;

    # Set file permissions
    find /path/to/aikeedo -type f -exec chmod 644 {} \;
    ```
  </Step>

  <Step title="Verify Virtual Host Settings">
    Double-check that all virtual host settings are correctly configured:

    * **Document Root**: Must point to `/path/to/aikeedo/public` (not the root directory)
    * **Server Name/Alias**: Must match your domain exactly
    * **PHP Handler**: Configured correctly (PHP-FPM for Nginx, mod\_php or PHP-FPM for Apache)
    * **Rewrite Rules**: Enabled and properly configured to route all requests to `index.php`
  </Step>

  <Step title="Test Configuration">
    After making changes:

    1. Test web server configuration:
       * Nginx: `sudo nginx -t`
       * Apache: `sudo apache2ctl configtest`

    2. Reload your web server:
       ```bash theme={null}
       # Nginx
       sudo systemctl reload nginx

       # Apache
       sudo systemctl reload apache2
       ```

    3. Visit your domain - you should be automatically redirected to `/install`

    <Check>
      If you're redirected to `/install`, your server configuration is correct.
    </Check>
  </Step>
</Steps>

<Warning>
  All requests must be rewritten to `/public/index.php` for the application to function correctly. Without proper rewrite rules, you'll encounter 404 errors on all routes except the home page.
</Warning>

***

### Database Connection Issues

**Symptoms:**

* Cannot connect to database during installation
* Database error messages in installation wizard
* Installation fails at database configuration step

**Cause:**
Incorrect database credentials, missing database, or insufficient permissions.

**Solution:**

1. **Verify Database Credentials**
   * **Database name**: Must be exact (case-sensitive)
   * **Username**: Database user with proper permissions
   * **Password**: Correct password for the database user
   * **Host**: Usually `localhost`, but may be different on some hosts

2. **Check Database Server**
   * Ensure the database server (MySQL/MariaDB) is running
   * Verify the database is accessible from your web server
   * Confirm the database exists and is empty

3. **Verify User Permissions**

   The database user must have these permissions:

   * SELECT, INSERT, UPDATE, DELETE
   * CREATE, DROP, INDEX, ALTER

   <Tip>
     If unsure, grant ALL PRIVILEGES to the database user for the specific database.
   </Tip>

4. **Check PHP Extensions**

   Verify that required PHP database extensions are installed:

   * `mysqli` for MySQL
   * `pdo_mysql` for PDO support

   Check with:

   ```bash theme={null}
   php -m | grep -i mysql
   ```

If problems persist, try creating a new database and user with full permissions.

***

### 500 Internal Server Error During Installation

**Symptoms:**

* HTTP 500 error before or during installation
* Blank page with 500 status code
* Generic server error message

**Cause:**
PHP configuration issues, incorrect file permissions, or insufficient server resources.

**Solution:**

<Steps>
  <Step title="Check Error Logs">
    Review server error logs for specific error messages:

    **Apache:**

    ```bash theme={null}
    tail -f /var/log/apache2/error.log
    # or
    tail -f /var/log/httpd/error_log
    ```

    **Nginx:**

    ```bash theme={null}
    tail -f /var/log/nginx/error.log
    ```

    Error logs will reveal the exact issue.
  </Step>

  <Step title="Verify PHP Version">
    Ensure you're running PHP 8.2 or later:

    ```bash theme={null}
    php -v
    ```

    Verify all required extensions are installed:

    ```bash theme={null}
    php -m
    ```
  </Step>

  <Step title="Set Correct Ownership and Permissions">
    ```bash theme={null}
    # Set ownership (replace www-data with your web server user)
    chown -R www-data:www-data /path/to/aikeedo

    # Set directory permissions
    find /path/to/aikeedo -type d -exec chmod 755 {} \;

    # Set file permissions
    find /path/to/aikeedo -type f -exec chmod 644 {} \;
    ```

    <Note>
      Common web server users: `www-data` (Ubuntu/Debian), `apache` (CentOS/RHEL), `nginx` (Nginx)
    </Note>
  </Step>

  <Step title="Restart PHP-FPM (if applicable)">
    If using PHP-FPM:

    ```bash theme={null}
    sudo systemctl restart php8.2-fpm
    ```

    Replace `8.2` with your PHP version.
  </Step>

  <Step title="Increase PHP Memory Limit">
    Edit your `php.ini` file:

    ```ini theme={null}
    memory_limit = 256M
    ```

    Restart your web server after making changes.
  </Step>
</Steps>

***

### Installation Wizard Not Loading

**Symptoms:**

* Blank white page when accessing installation
* Installation wizard doesn't appear
* JavaScript errors in browser console

**Cause:**
PHP errors, insufficient server resources, or missing files.

**Solution:**

1. **Check PHP Error Logs**: Review PHP error logs for fatal errors or warnings
2. **Clear Browser Cache**: Hard refresh (Ctrl+Shift+R or Cmd+Shift+R) or try a different browser
3. **Verify SSL Certificate**: If using HTTPS, ensure your SSL certificate is valid
4. **Check File Permissions**: Verify web server can read all files in the `public` directory
5. **Confirm PHP Extensions**: Ensure all required extensions are installed (see [Server Requirements](/overview/server-requirements))
6. **Check Server Resources**: Verify sufficient CPU and RAM are available

<Tip>
  Try accessing the site from an incognito/private browsing window to rule out browser cache issues.
</Tip>

***

## Configuration Issues

### "Does Not Allow the Value" Error

**Symptoms:**

* Error message: "Does not allow the value"
* Occurs after installation when trying to use features

**Cause:**
The Site Domain value is missing in General Settings.

**Solution:**

1. Log in to the admin panel
2. Navigate to **Settings > General**
3. Locate the "Site Domain" field
4. Enter your domain without protocol or paths (e.g., `yourdomain.com`)
5. Enable SSL if you have an SSL certificate
6. Click "Save changes"

**Related Documentation:**

* [Initial Setup - Configuring Site Domain](/setup/initial-setup#configuring-your-site-domain)

***

### Cannot Select Models or Send Prompts

**Symptoms:**

* Browser console shows JavaScript errors
* Unable to select AI models in dropdown
* Cannot send prompts or generate content
* Tools missing from sidebar

**Cause:**
Features and models are not enabled globally, or plan configuration is incomplete.

**Solution:**

<Steps>
  <Step title="Enable Features Globally">
    1. Navigate to **Settings > Features** in the admin panel
    2. Enable the features you want to offer (Chat, Writer, Coder, etc.)
    3. Click "Save changes"

    <Note>
      Enabling features globally makes them available but they still need to be configured in plans.
    </Note>
  </Step>

  <Step title="Enable Models Globally">
    1. Go to **Settings > Models**
    2. Enable the AI models you want to make available
    3. Click "Save changes"
  </Step>

  <Step title="Configure Plan Settings">
    1. Navigate to the **Plans** page in the admin panel
    2. Find the plan your users are subscribed to
    3. Edit the plan configuration:
       * Enable desired features
       * Enable desired models
       * Set credit allocations
    4. **Important:** Check the "Update snapshots" box before saving
    5. Click "Save changes"

    <Warning>
      If you don't check "Update snapshots," changes will only apply to new subscriptions, not existing ones.
    </Warning>
  </Step>

  <Step title="Verify Configuration">
    1. Log in as a test user
    2. Verify tools appear in the sidebar
    3. Test selecting a model and generating content

    <Check>
      Users should now be able to access features and generate content.
    </Check>
  </Step>
</Steps>

**Related Documentation:**

* [Plans, Snapshots & Subscriptions](/billing/plans-snapshots-subscriptions)
* [Application Configuration](/setup/configuration)

***

### 500 Error on Image Generator or Video Generator

**Symptoms:**

* Imagine (image generator) page returns HTTP 500 error
* Video generator page returns HTTP 500 error
* Server error logs show credit ratio issues

**Cause:**
Credit ratios are not configured for all enabled models.

**Solution:**

1. Navigate to **Settings > Credit Ratios** in the admin panel
2. Review all enabled AI models
3. Ensure **every enabled model** has a credit ratio configured
4. Set appropriate credit values for each model
5. Click "Save changes"

<Tip>
  If you're unsure about credit ratios, start with the default suggestions and adjust based on your pricing strategy.
</Tip>

**Related Documentation:**

* [Unified Credit System](/billing/unified-credit-system)
* [Application Configuration](/setup/configuration)

***

### Save Button Does Nothing

**Symptoms:**

* Clicking "Save changes" or other save buttons in the admin panel has no effect
* No error message appears
* Page appears to be unresponsive after clicking save
* Changes are not saved

**Cause:**
Most commonly a backend PHP error that's preventing the request from completing. Can also be a frontend JavaScript issue.

**Solution:**

<Steps>
  <Step title="Check Browser Console for Frontend Errors">
    Before clicking the save button, check for frontend errors:

    1. Open your browser's developer console:
       * **Chrome/Edge**: Press `F12` or `Ctrl+Shift+I` (Windows/Linux) / `Cmd+Option+I` (Mac)
       * **Firefox**: Press `F12` or `Ctrl+Shift+K` (Windows/Linux) / `Cmd+Option+K` (Mac)
       * **Safari**: Enable Developer menu first, then press `Cmd+Option+I`

    2. Look for any red error messages in the console

    3. Review error details - they often indicate the specific issue

    <Note>
      If you see errors in the console before clicking save, the issue is likely frontend-related. Note the error messages for troubleshooting.
    </Note>
  </Step>

  <Step title="Check Server Error Logs (Apache/Nginx)">
    If no frontend errors are visible, first check server-level error logs, as the issue might occur before the request reaches PHP:

    1. **Locate your web server error log**:
       ```bash theme={null}
       # Apache
       /var/log/apache2/error.log
       # or
       /var/log/httpd/error_log

       # Nginx
       /var/log/nginx/error.log
       ```

    2. **View recent errors**:
       ```bash theme={null}
       tail -f /path/to/error.log
       ```

    3. **Click the save button** while monitoring the log

    4. **Review any error messages** that appear

    <Note>
      Server-level errors can include issues like request timeouts, connection problems, or web server configuration errors that prevent requests from reaching PHP.
    </Note>
  </Step>

  <Step title="Check PHP Error Logs (Backend Issue)">
    If no server-level errors are found, check PHP error logs:

    1. **Locate your PHP error log** (common locations):
       ```bash theme={null}
       # PHP-FPM
       /var/log/php8.2-fpm.log
       # or check php.ini for error_log location
       # You can find it with: php -i | grep error_log
       ```

    2. **View recent errors**:
       ```bash theme={null}
       tail -f /path/to/php-error.log
       ```

    3. **Click the save button** while monitoring the log

    4. **Review the error message** that appears in the log

    <Tip>
      The error log will show the exact PHP error preventing the save operation from completing. Common issues include database errors, permission problems, or missing dependencies.
    </Tip>
  </Step>

  <Step title="Enable DEBUG Mode and Check API Response">
    Alternatively, enable DEBUG mode to get more detailed error information:

    1. **Enable DEBUG mode** from the admin panel:
       * Navigate to **Status** page in the admin panel
       * Enable DEBUG mode using the toggle or button provided

    2. **Open your browser's developer console** (see step 1 above)

    3. **Navigate to the Network tab** in the developer console

    4. **Click the save button** again

    5. **Look for the API request** that was made when you clicked save (usually shows as a POST request)

    6. **Click on the request** to view details:
       * Check the **Status Code** (should be between 200 and 299 for success, 4xx/5xx for errors)
       * Check the **Response** tab to see the response body
       * Review any error messages in the response

    <Warning>
      Remember to disable DEBUG mode from the Status page after troubleshooting, as it can expose sensitive information in production environments.
    </Warning>
  </Step>

  <Step title="Address the Specific Error">
    Based on the error information you've gathered:

    * **Database errors**: Check database connection and permissions
    * **Permission errors**: Verify file/directory permissions (see [500 Internal Server Error](#500-internal-server-error-during-installation))
    * **Missing dependencies**: Ensure all required PHP extensions are installed
    * **Frontend JavaScript errors**: Check for conflicting scripts or browser compatibility issues

    <Tip>
      The specific error message will guide you to the exact solution. Common fixes include updating file permissions, fixing database credentials, or installing missing PHP extensions.
    </Tip>
  </Step>
</Steps>

**Related Documentation:**

* [500 Internal Server Error During Installation](#500-internal-server-error-during-installation) - Permission and PHP configuration issues
* [Database Connection Issues](#database-connection-issues) - Database-related errors

***

## Database Issues

### MySQL Server Has Gone Away

**Symptoms:**

* Error message: "MySQL server has gone away"
* Database connection drops during requests
* Long-running operations fail

**Cause:**
MySQL server timeout or packet size limitations.

**Solution:**

<Tabs>
  <Tab title="Server Timeout Fix">
    **Problem:** MySQL server times out and closes the connection.

    **Solution:** Update your `my.cnf` configuration file:

    ```ini theme={null}
    [mysqld]
    wait_timeout = 28800
    ```

    This sets the timeout to 8 hours. Adjust as needed for your use case.
  </Tab>

  <Tab title="Packet Size Fix">
    **Problem:** MySQL receives packets that are too large or incorrect.

    **Solution:** Increase the max packet size in `my.cnf`:

    ```ini theme={null}
    [mysqld]
    max_allowed_packet = 128M
    ```

    This allows larger data packets to be processed.
  </Tab>

  <Tab title="InnoDB Log Size">
    **Problem:** InnoDB log file size is insufficient.

    **Solution:** Increase the log file size in `my.cnf`:

    ```ini theme={null}
    [mysqld]
    innodb_log_file_size = 128M
    ```

    Or larger, depending on your data volume.
  </Tab>
</Tabs>

<Warning>
  After modifying `my.cnf`, you must restart your MySQL server for changes to take effect:

  ```bash theme={null}
  sudo systemctl restart mysql
  ```

  or

  ```bash theme={null}
  sudo service mysql restart
  ```
</Warning>

**Finding my.cnf:**

Common locations for the MySQL configuration file:

* Linux: `/etc/my.cnf` or `/etc/mysql/my.cnf`
* macOS: `/etc/my.cnf`
* Windows: `C:\ProgramData\MySQL\MySQL Server X.X\my.ini`

<Note>
  If you're on shared hosting and don't have access to `my.cnf`, contact your hosting provider to request these changes.
</Note>

***

## Feature-Specific Issues

### Auto-Generated Titles Don't Match Content Language

**Symptoms:**

* AI generates titles in Spanish when content is in another language
* Title language doesn't match the generated content language

**Cause:**
AI models sometimes generate titles in their default language despite instructions.

**Solution:**

<Tabs>
  <Tab title="Option 1: Modify Prompts">
    Customize the title generation prompts in these files:

    ```
    /src/Ai/Infrastructure/Services/OpenAi/TitleGeneratorService.php
    /src/Ai/Infrastructure/Services/Anthropic/TitleGeneratorService.php
    /src/Ai/Infrastructure/Services/Cohere/TitleGeneratorService.php
    ```

    Strengthen the language instruction in the prompt to emphasize matching the content language.

    <Warning>
      Custom code modifications will need to be reapplied after app updates.
    </Warning>
  </Tab>

  <Tab title="Option 2: Configure Plan Models">
    Some AI models are better at following language instructions than others:

    1. Navigate to **Plans** in your admin panel
    2. Edit the plan that's experiencing title language issues
    3. In the plan configuration, change the title generation model
    4. **Important:** Check the "Update snapshot" checkbox before saving
    5. Save the plan changes and test title generation
  </Tab>
</Tabs>

***

### Uploaded Files Return 404 Not Found Errors

**Symptoms:**

* Uploaded files show "not found" or 404 errors
* Generated files (images, videos, audio, documents etc.) are inaccessible
* Files exist in storage but cannot be accessed via URL
* Browser shows 404 when clicking file links

**Cause:**
File grouping enabled on local storage, secure URLs enabled, incorrect document root configuration, or file permission issues.

**Solution:**

<Steps>
  <Step title="Disable File Grouping (if using local storage)">
    If you're experiencing file access issues with local storage, try disabling file grouping:

    1. Log in to the admin panel
    2. Navigate to **Settings > Storage**
    3. Locate the "File Grouping" option
    4. Change the value to **"None"**
    5. Click "Save changes"

    <Note>
      File grouping and secure URLs are optimized for cloud storage (S3, DigitalOcean Spaces, etc.) and may cause compatibility issues on some local storage configurations, particularly on cPanel-based hosting. If files are inaccessible, disabling these options often resolves the issue.
    </Note>
  </Step>

  <Step title="Disable Secure URLs">
    If you're using local storage without special security requirements:

    1. In **Settings > Storage**
    2. Locate the "Secure URLs" option
    3. **Turn off** the "Secure URLs" option
    4. Click "Save changes"

    <Warning>
      If files were uploaded with Secure URLs enabled, you may need to re-upload them after disabling this option.
    </Warning>
  </Step>

  <Step title="Verify Document Root Configuration">
    If your domain's document root is set to `public_html` instead of `public`:

    1. Open your `.env` file in the root directory
    2. Find the line with `PUBLIC_DIR` (it may be commented out with `#`)
    3. Ensure it's set correctly:
       ```bash theme={null}
       PUBLIC_DIR=public_html
       ```
    4. Remove the `#` symbol if present at the beginning
    5. Save the file

    <Note>
      This is particularly important for cPanel users where the default document root is `public_html`.
    </Note>
  </Step>

  <Step title="Check File Permissions">
    Ensure the web server has read access to uploaded files:

    ```bash theme={null}
    # Navigate to your Aikeedo directory
    cd /path/to/aikeedo

    # Set correct permissions for storage directory
    chmod -R 755 storage/

    # Set correct ownership (replace www-data with your web server user)
    chown -R www-data:www-data storage/
    ```

    Common web server users:

    * Ubuntu/Debian: `www-data`
    * CentOS/RHEL: `apache`
    * Nginx: `nginx`
  </Step>

  <Step title="Check Cloud Storage CORS Configuration">
    If you're using cloud storage (AWS S3, DigitalOcean Spaces, etc.), CORS issues may prevent file access:

    1. **Check your cloud storage CORS configuration:**
       * Ensure your bucket allows requests from your domain
       * Verify that the GET method is allowed (generally sufficient for file access)
       * Check that the correct headers are permitted

    2. **Example CORS configuration for AWS S3:**
       ```json theme={null}
       [
         {
           "AllowedHeaders": ["*"],
           "AllowedMethods": ["GET"],
           "AllowedOrigins": ["https://yourdomain.com", "https://www.yourdomain.com"]
         }
       ]
       ```

    3. **Verify your storage configuration:**
       * Check **Settings > Storage** in your admin panel
       * Ensure cloud storage credentials are correct
       * Verify the bucket/container name and region are accurate

    <Warning>
      CORS misconfiguration can cause files to appear uploaded but return 404 errors when accessed. Always test file access after making CORS changes.
    </Warning>
  </Step>

  <Step title="Verify Storage Path">
    Check that your storage path is correctly configured:

    1. Go to **Settings > Storage** in the admin panel
    2. Verify the storage driver is set correctly (Local, S3, etc.)
    3. If using local storage, ensure the path is correct
    4. Test by uploading a new file

    <Check>
      If the new file is accessible, the configuration is correct. You may need to re-upload older files.
    </Check>
  </Step>

  <Step title="Clear Application Cache">
    After making configuration changes:

    1. Navigate to **Status** page in the admin panel
    2. Click "Clear cache" to clear the application cache
    3. Test file access again
  </Step>
</Steps>

<Tip>
  For production environments requiring secure file access or workspace-based file organization, cloud storage (S3, DigitalOcean Spaces) is recommended. File grouping and secure URL features are optimized for cloud storage and work most reliably in that environment, though they may also work on some local storage configurations.
</Tip>

**Related Documentation:**

* [Secure URLs](/advanced/secure-urls) - Configure secure file access
* [cPanel Installation](/setup/installation/cpanel) - Document root configuration for cPanel

***

### Generated Images/Videos Not Loading

**Symptoms:**

* Generated images or videos fail to display after creation
* Broken image/video placeholders appear instead of content
* 404 or 403 errors when accessing generated media files
* Files appear to generate successfully but cannot be viewed

**Cause:**
Incomplete initial setup, cloud storage CORS misconfiguration, incorrect `.env` file configuration (especially for cPanel installations), or Secure URLs/Group files settings enabled when using local storage.

**Solution:**

<Steps>
  <Step title="Verify Initial Setup Completion">
    Ensure you've completed all steps in the [Initial Setup Guide](/setup/initial-setup):

    1. Verify your site domain is configured correctly in **Settings > General**
    2. Check that storage settings are properly configured in **Settings > File storage**
    3. Ensure all required integrations are set up if using cloud storage

    <Warning>
      Skipping or incorrectly completing initial setup steps can prevent generated files from being accessible.
    </Warning>
  </Step>

  <Step title="Check Cloud Storage CORS Configuration">
    If you're using cloud storage (AWS S3, DigitalOcean Spaces, Cloudflare R2, etc.), CORS misconfiguration is a common cause:

    1. **Access your cloud storage provider's console** (AWS S3, DigitalOcean, etc.)
    2. **Navigate to your bucket/container settings**
    3. **Review CORS configuration** - it must allow requests from your domain
    4. **Update CORS rules** if needed:
    5. **Save the CORS configuration**
    6. **Test by generating a new image or video**

    <Note>
      CORS rules must include your exact domain (with protocol: `https://` or `http://`). Wildcards may not work for all storage providers.
    </Note>

    <Tip>
      See the [Cloud Storage Overview](/integrations/cloud-storage/overview) and provider-specific guides for detailed CORS configuration instructions.
    </Tip>
  </Step>

  <Step title="Check Secure URLs and Group Files Settings">
    The **Secure URLs** and **Group files** options should only be enabled when using cloud storage (AWS S3, DigitalOcean Spaces, etc.):

    1. Navigate to **Settings > File storage** in the admin panel
    2. Review the **Secure URLs** and **Group files** settings
    3. **If using local storage**, ensure both options are disabled:
       * **Secure URLs**: Should be turned **Off**
       * **Group files**: Should be set to **None**
    4. **If using cloud storage**, these options can be enabled as needed
    5. Click "Save changes"

    <Warning>
      **Secure URLs** and **Group files** are designed for cloud storage only. Enabling these options with local storage can cause generated files to be inaccessible.
    </Warning>

    <Note>
      Changing these settings only affects newly generated files. Files that were already generated with the previous settings will remain unchanged. If the issue stems from Secure URLs, previously generated files can be made accessible by fixing file permissions (see the "Verify Storage Path and Permissions" step below). Otherwise, you may need to regenerate images or videos after adjusting these settings.
    </Note>
  </Step>

  <Step title="Verify .env File Configuration (cPanel Users)">
    If you're using cPanel, the `.env` file configuration is critical:

    1. **Locate your `.env` file** in the Aikeedo root directory (not in `public_html`)
    2. **Find the `PUBLIC_DIR` setting** - it may be commented out with `#`
    3. **For main domain installations**, ensure it's set correctly:
       ```env theme={null}
       PUBLIC_DIR=public_html
       ```
    4. **Remove the `#` symbol** if the line is commented out
    5. **Save the file**

    <Warning>
      If you're using cPanel and the `PUBLIC_DIR` setting is missing or incorrect, generated files will not be accessible. This is a critical step that must be completed during installation.
    </Warning>

    <Note>
      For add-on domains or subdomains in cPanel where the document root points directly to the `public` folder, you may not need to set `PUBLIC_DIR` or it should be set to `public`. Refer to the [cPanel Installation Guide](/setup/installation/cpanel) for your specific setup.
    </Note>
  </Step>

  <Step title="Verify Storage Path and Permissions">
    Check that your storage configuration is correct:

    1. Navigate to **Settings > File storage** in the admin panel
    2. Verify the storage driver is set correctly (Local, S3, etc.)
    3. If using local storage, ensure the storage path is writable:
       ```bash theme={null}
       # Check storage directory permissions
       ls -la /path/to/aikeedo/public/uploads/

       # Set correct permissions if needed
       chmod -R 755 /path/to/aikeedo/public/uploads/
       chown -R www-data:www-data /path/to/aikeedo/public/uploads/
       ```
    4. If using cloud storage, verify:
       * Bucket/container name is correct
       * Region is correctly configured
       * Access keys are valid and have proper permissions
       * Bucket/container exists and is accessible

    <Check>
      Test by generating a new image or video. If it loads correctly, the configuration is working.
    </Check>
  </Step>
</Steps>

<Warning>
  **For cPanel users:** If you skipped or incorrectly completed the `.env` file configuration step during installation (specifically the `PUBLIC_DIR=public_html` setting), generated files will not load correctly. This is one of the most common causes of this issue on cPanel hosting. Refer to the [cPanel Installation Guide](/setup/installation/cpanel) and ensure you've completed the "Update the Environment File" step correctly.
</Warning>

**Related Documentation:**

* [Initial Setup Guide](/setup/initial-setup) - Complete setup configuration
* [cPanel Installation](/setup/installation/cpanel) - Critical `.env` file configuration
* [Cloud Storage Overview](/integrations/cloud-storage/overview) - Cloud storage setup and CORS configuration
* [Secure URLs](/advanced/secure-urls) - Secure file access configuration

***

## Additional Troubleshooting Steps

If you're still experiencing issues after trying the solutions above:

1. **Fresh Installation**: Consider a clean reinstall with fresh Aikeedo files
2. **Server Configuration**: Review web server configuration (Apache/Nginx) for PHP applications
3. **PHP Configuration**: Check `php.ini` for settings like:
   * `max_execution_time`
   * `upload_max_filesize`
   * `post_max_size`
   * `memory_limit`
4. **Hosting Environment**: Contact your hosting provider to ensure no server-side restrictions

## Getting Additional Help

If you've tried the solutions above and still need assistance:

### Before Contacting Support

1. **Check Error Logs:**
   * Browser console (F12 in most browsers)
   * Server error logs (`/var/log/apache2/error.log` or `/var/log/nginx/error.log`)
   * Application logs
   * PHP error logs

2. **Verify Configuration:**
   * Review [Initial Setup](/setup/initial-setup)
   * Check [Application Configuration](/setup/configuration)
   * Verify [Server Requirements](/overview/server-requirements)

3. **Clear Caches:**
   * Clear browser cache (Ctrl+Shift+R or Cmd+Shift+R)
   * Clear application cache from admin panel Status page

### Need Additional Help?

<Card title="Professional Support" icon="headset" href="https://aikeedo.com/support/">
  Get expert help from our team with a paid support subscription
</Card>

For support plan options and pricing, visit [https://aikeedo.com/support/](https://aikeedo.com/support/).

**Before contacting support:**

* Ensure you have an active [support plan subscription](https://aikeedo.com/support/)
* Have your Aikeedo license key ready for validation

**When contacting support, include:**

* Your Aikeedo license key (for purchase validation)
* Detailed description of the issue
* Complete error messages (screenshots if possible)
* Steps to reproduce the problem
* PHP version and server environment details
* Aikeedo version number
* Relevant error log entries
* What troubleshooting steps you've already tried

<Warning>
  Support is only available to users with active support plan subscriptions. Requests without valid license keys or active support plans will not be processed.
</Warning>

<Tip>
  The more detailed information you provide, the faster our support team can help resolve your issue.
</Tip>

***

## Related Guides

* [Installation Guide](/setup/installation)
* [Initial Setup](/setup/initial-setup)
* [Application Configuration](/setup/configuration)
* [Server Requirements](/overview/server-requirements)
* [Plans, Snapshots & Subscriptions](/billing/plans-snapshots-subscriptions)