Assets Not Working?
Complete Troubleshooting and Fix Guide
If a downloaded script, Docker template, database seed, server configuration, or UI component from Clayi Assets is not executing as expected or throwing terminal errors, do not worry. Technical issues usually stem from environment mismatches, missing system dependencies, permission restrictions, or version incompatibilities. This comprehensive troubleshooting guide covers the most common execution errors across all asset categories and provides step-by-step solutions to get your files running smoothly.
1. Python & Terminal Script Issues (.py, .sh, .ps1)
Automation scripts require the correct runtime environment, execution permissions, and dependencies to run properly.
A. "Permission Denied" Error (Linux / macOS)
Cause: The downloaded Bash or Shell script lacks executable file permissions on your filesystem.
Solution: Open your terminal and grant execution permission by running chmod +x your_script.sh before launching the script with ./your_script.sh.
B. "ModuleNotFoundError" or Missing Dependencies (Python)
Cause: The Python script relies on external libraries (such as requests, urllib3, or psycopg2) that are not yet installed in your environment.
Solution: Create a fresh virtual environment by running python -m venv venv, activate it (source venv/bin/activate), and install missing packages using pip install -r requirements.txt or pip install package_name.
C. "SyntaxError" or Invalid Python Version
Cause: Your system is invoking an older Python 2.7 runtime instead of Python 3.8+.
Solution: Explicitly invoke the Python 3 binary by running python3 your_script.py instead of python your_script.py.
2. Docker Compose & Container Template Errors (.yml, .Dockerfile)
Container templates require an active Docker Engine daemon and correct port mappings.
A. "docker-compose: command not found"
Cause: You are using Docker Compose V2, where the hyphenated command is deprecated.
Solution: Use the modern V2 CLI syntax: run docker compose up -d instead of docker-compose up -d.
B. "Port is already allocated" Error
Cause: Another service on your machine is already using port 80, 443, 3000, or 5432.
Solution: Open docker-compose.yml in a text editor and change the host port mapping (for example, change "80:80" to "8080:80" or "3000:3000" to "3001:3000").
C. Database Connection Refused inside Containers
Cause: The application container launched before the PostgreSQL/MySQL container finished its initial health check.
Solution: Ensure the depends_on and healthcheck blocks are enabled in your Compose file, or restart the web container after 10 seconds using docker compose restart web.
3. Database Import & Dataset Failures (.sql, .json)
A. "Unknown Database" or "Access Denied" (SQL Dumps)
Cause: Target database does not exist prior to importing the seed dump.
Solution: Log into your MySQL/Postgres prompt and create the database manually first: CREATE DATABASE clayi_db; then re-run the import command.
4. Server Configuration Errors (.conf, .htaccess)
A. Nginx "502 Bad Gateway" or Syntax Error
Cause: PHP-FPM socket path mismatch or invalid Directive in Nginx config.
Solution: Verify your installed PHP version (e.g., php8.2-fpm vs php8.1-fpm) and check socket path in fastcgi_pass. Always test configuration syntax with nginx -t before reloading server services.
5. UI Component Styling Failures (.html, .css)
A. Unstyled HTML or Broken Tailwind Classes
Cause: Tailwind CSS compiler is not scanning the HTML file path or CDN script is missing.
Solution: For quick testing, add the Tailwind CDN script inside your HTML <head>: <script src="https://cdn.tailwindcss.com"></script>, or include the file path inside tailwind.config.js content array.
How to Report a Broken Asset to Clayi Team
If you have verified your local environment and suspect a file hosted on Clayi Assets is corrupt, missing dependencies, or broken, please reach out to our team through our official Contact Page. Please include the asset URL, file name, and your operating system details for quick resolution.
Disclaimer & Legal Notice
The troubleshooting steps, terminal commands, and configuration remedies provided in this guide are offered for informational and testing purposes only. Clayi Ecosystem makes no representations or warranties regarding system outcomes when executing commands on local machines or production servers. Users assume full responsibility for inspecting code, verifying command syntax, and executing backups prior to running troubleshooting commands on their infrastructure.
