Skip to main content

​
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
  2. You have the latest version of Aikeedo files
  3. You’ve followed the installation guide carefully
  4. You’ve completed initial setup steps

​
Quick Navigation

Find your issue and click to jump to the solution:

​
Installation Issues

​
Configuration Issues

​
Database Issues

​
Feature-Specific Issues

​
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:
1

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.
2

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.
3

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, or incorrect permissions. Solution:
1

Verify Document Root

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
2

Check File Extraction

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

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

Verify .htaccess File

Ensure the .htaccess file is present in the public directory.
Hidden files may not be visible by default. Enable “Show hidden files” in your FTP client or file manager.

​
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
    If unsure, grant ALL PRIVILEGES to the database user for the specific database.
  4. 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:
1

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.
2

Verify PHP Version

Ensure you’re running PHP 8.2 or later:
php -v
Verify all required extensions are installed:
php -m
3

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)
4

Restart PHP-FPM (if applicable)

If using PHP-FPM:
sudo systemctl restart php8.2-fpm
Replace 8.2 with your PHP version.
5

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:
  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)
  6. 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:
  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:

​
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:
1

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”
Enabling features globally makes them available but they still need to be configured in plans.
2

Enable Models Globally

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

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”
If you don’t check “Update snapshots,” changes will only apply to new subscriptions, not existing ones.
4

Verify Configuration

  1. Log in as a test user
  2. Verify tools appear in the sidebar
  3. 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:
  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”
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
or
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:
1

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”
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.
2

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”
If files were uploaded with Secure URLs enabled, you may need to re-upload them after disabling this option.
3

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: 
    PUBLIC_DIR=public_html
  4. Remove the # symbol if present at the beginning
  5. Save the file
This is particularly important for cPanel users where the default document root is public_html.
4

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
5

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: 
    [
  {
    "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
CORS misconfiguration can cause files to appear uploaded but return 404 errors when accessed. Always test file access after making CORS changes.
6

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
If the new file is accessible, the configuration is correct. You may need to re-upload older files.
7

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
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:

​
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:
  3. 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: 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.
⌘I