Troubleshooting

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:

Your server meets all server requirements
You have the latest version of Aikeedo files
You’ve followed the installation guide carefully
You’ve completed initial setup steps

Find your issue and click to jump to the solution:

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:

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.

Test Redirection

Visit your domain (e.g., https://yourdomain.com). You should be automatically redirected to https://yourdomain.com/install.

If the redirect works, your domain is configured correctly.

cPanel Users

If you’re using cPanel and cannot change the document root for your main domain, follow the dedicated cPanel Installation Guide.

The cPanel installation process differs from the standard installation due to control panel limitations.

Related Documentation:

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:

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

Accessing your domain should automatically redirect you to /install if the document root is correctly configured.

Configure Web Server

Configure your web server to serve PHP applications and rewrite all requests to /public/index.php:

Nginx
Apache

Ensure your server block is configured correctly:

/etc/nginx/sites-available/aikeedo

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;
    }
}

After configuring, test your Nginx configuration: sudo nginx -t and reload: sudo systemctl reload nginxAdjust 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)

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.

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.

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.

Check File Extraction

Verify all Aikeedo files are extracted correctly and the public directory exists with all necessary files.

Set File Permissions

Ensure the web server has appropriate permissions:

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

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

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

Test Configuration

After making changes:

Test web server configuration:
- Nginx: sudo nginx -t
- Apache: sudo apache2ctl configtest

Reload your web server:

# Nginx
sudo systemctl reload nginx

# Apache
sudo systemctl reload apache2

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

If you’re redirected to /install, your server configuration is correct.

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.

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:

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
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
Verify User Permissions The database user must have these permissions:
- SELECT, INSERT, UPDATE, DELETE
- CREATE, DROP, INDEX, ALTER
If unsure, grant ALL PRIVILEGES to the database user for the specific database.
Check PHP Extensions Verify that required PHP database extensions are installed:
- mysqli for MySQL
- pdo_mysql for PDO support
Check with:
```
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:

Check Error Logs

Review server error logs for specific error messages:Apache:

tail -f /var/log/apache2/error.log
# or
tail -f /var/log/httpd/error_log

Nginx:

tail -f /var/log/nginx/error.log

Error logs will reveal the exact issue.

Verify PHP Version

Ensure you’re running PHP 8.2 or later:

php -v

Verify all required extensions are installed:

php -m

Set Correct Ownership and Permissions

# 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 {} \;

Common web server users: www-data (Ubuntu/Debian), apache (CentOS/RHEL), nginx (Nginx)

Restart PHP-FPM (if applicable)

If using PHP-FPM:

sudo systemctl restart php8.2-fpm

Replace 8.2 with your PHP version.

Increase PHP Memory Limit

Edit your php.ini file:

memory_limit = 256M

Restart your web server after making changes.

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:

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

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

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:

Log in to the admin panel
Navigate to Settings > General
Locate the “Site Domain” field
Enter your domain without protocol or paths (e.g., yourdomain.com)
Enable SSL if you have an SSL certificate
Click “Save changes”

Related Documentation:

Initial Setup - Configuring 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:

Enable Features Globally

Navigate to Settings > Features in the admin panel
Enable the features you want to offer (Chat, Writer, Coder, etc.)
Click “Save changes”

Enabling features globally makes them available but they still need to be configured in plans.

Enable Models Globally

Go to Settings > Models
Enable the AI models you want to make available
Click “Save changes”

Configure Plan Settings

Navigate to the Plans page in the admin panel
Find the plan your users are subscribed to
Edit the plan configuration:
- Enable desired features
- Enable desired models
- Set credit allocations
Important: Check the “Update snapshots” box before saving
Click “Save changes”

If you don’t check “Update snapshots,” changes will only apply to new subscriptions, not existing ones.

Verify Configuration

Log in as a test user
Verify tools appear in the sidebar
Test selecting a model and generating content

Users should now be able to access features and generate content.

Related Documentation:

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:

Navigate to Settings > Credit Ratios in the admin panel
Review all enabled AI models
Ensure every enabled model has a credit ratio configured
Set appropriate credit values for each model
Click “Save changes”

If you’re unsure about credit ratios, start with the default suggestions and adjust based on your pricing strategy.

Related Documentation:

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:

Server Timeout Fix
Packet Size Fix
InnoDB Log Size

Problem: MySQL server times out and closes the connection.Solution: Update your my.cnf configuration file:

[mysqld]
wait_timeout = 28800

This sets the timeout to 8 hours. Adjust as needed for your use case.

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

sudo systemctl restart mysql

sudo service mysql restart

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

If you’re on shared hosting and don’t have access to my.cnf, contact your hosting provider to request these changes.

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:

Option 1: Modify Prompts
Option 2: Configure Plan Models

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.

Custom code modifications will need to be reapplied after app updates.

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:

Disable File Grouping (if using local storage)

If you’re experiencing file access issues with local storage, try disabling file grouping:

Log in to the admin panel
Navigate to Settings > Storage
Locate the “File Grouping” option
Change the value to “None”
Click “Save changes”

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.

Disable Secure URLs

If you’re using local storage without special security requirements:

In Settings > Storage
Locate the “Secure URLs” option
Turn off the “Secure URLs” option
Click “Save changes”

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

Verify Document Root Configuration

If your domain’s document root is set to public_html instead of public:

Open your .env file in the root directory
Find the line with PUBLIC_DIR (it may be commented out with #)
Ensure it’s set correctly:
```
PUBLIC_DIR=public_html
```
Remove the # symbol if present at the beginning
Save the file

This is particularly important for cPanel users where the default document root is public_html.

Check File Permissions

Ensure the web server has read access to uploaded files:

# 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

Check Cloud Storage CORS Configuration

If you’re using cloud storage (AWS S3, DigitalOcean Spaces, etc.), CORS issues may prevent file access:

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

Example CORS configuration for AWS S3:

[
  {
    "AllowedHeaders": ["*"],
    "AllowedMethods": ["GET"],
    "AllowedOrigins": ["https://yourdomain.com", "https://www.yourdomain.com"]
  }
]

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

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

Verify Storage Path

Check that your storage path is correctly configured:

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

If the new file is accessible, the configuration is correct. You may need to re-upload older files.

Clear Application Cache

After making configuration changes:

Navigate to Status page in the admin panel
Click “Clear cache” to clear the application cache
Test file access again

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.

Related Documentation:

Secure URLs - Configure secure file access
cPanel Installation - Document root configuration for cPanel

Additional Troubleshooting Steps

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

Fresh Installation: Consider a clean reinstall with fresh Aikeedo files
Server Configuration: Review web server configuration (Apache/Nginx) for PHP applications
PHP Configuration: Check php.ini for settings like:
- max_execution_time
- upload_max_filesize
- post_max_size
- memory_limit
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

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
Verify Configuration:
- Review Initial Setup
- Check Application Configuration
- Verify Server Requirements
Clear Caches:
- Clear browser cache (Ctrl+Shift+R or Cmd+Shift+R)
- Clear application cache from admin panel Status page

Need Additional Help?

Professional Support

Get expert help from our team with a paid support subscription

For support plan options and pricing, visit https://aikeedo.com/support/. Before contacting support:

Ensure you have an active support plan subscription
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

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

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

Overview

Installation & Setup

Website Basics

Email

Authentication

Integrations

Billing

Advanced

Versioning

Overview

Before You Begin

Quick Navigation

Installation Issues

Configuration Issues

Database Issues

Feature-Specific Issues

Installation Issues

Assets Not Loading

404 or 403 Errors During Installation

Database Connection Issues

500 Internal Server Error During Installation

Installation Wizard Not Loading

Configuration Issues

”Does Not Allow the Value” Error

Cannot Select Models or Send Prompts

500 Error on Image Generator or Video Generator

Database Issues

MySQL Server Has Gone Away

Feature-Specific Issues

Auto-Generated Titles Don’t Match Content Language

Uploaded Files Return 404 Not Found Errors

Additional Troubleshooting Steps

Getting Additional Help

Before Contacting Support

Need Additional Help?

Professional Support

Overview

Installation & Setup

Website Basics

Email

Authentication

Integrations

Billing

Advanced

Versioning

​Overview

​Before You Begin

​Quick Navigation

​Installation Issues

​Configuration Issues

​Database Issues

​Feature-Specific Issues

​Installation Issues

​Assets Not Loading

​404 or 403 Errors During Installation

​Database Connection Issues

​500 Internal Server Error During Installation

​Installation Wizard Not Loading

​Configuration Issues

​”Does Not Allow the Value” Error

​Cannot Select Models or Send Prompts

​500 Error on Image Generator or Video Generator

​Database Issues

​MySQL Server Has Gone Away

​Feature-Specific Issues

​Auto-Generated Titles Don’t Match Content Language

​Uploaded Files Return 404 Not Found Errors

​Additional Troubleshooting Steps

​Getting Additional Help

​Before Contacting Support

​Need Additional Help?

Professional Support

​Related Guides

Overview

Before You Begin

Quick Navigation

Installation Issues

Configuration Issues

Database Issues

Feature-Specific Issues

Installation Issues

Assets Not Loading

404 or 403 Errors During Installation

Database Connection Issues

500 Internal Server Error During Installation

Installation Wizard Not Loading

Configuration Issues

”Does Not Allow the Value” Error

Cannot Select Models or Send Prompts

500 Error on Image Generator or Video Generator

Database Issues

MySQL Server Has Gone Away

Feature-Specific Issues

Auto-Generated Titles Don’t Match Content Language

Uploaded Files Return 404 Not Found Errors

Additional Troubleshooting Steps

Getting Additional Help

Before Contacting Support

Need Additional Help?

Related Guides