Skip to main content

Rebrand Engine Troubleshooting

Common issues and solutions when using LibreApps Desktop Rebrand Engine.

Overview​

While the rebrand engine is designed to be robust, you may encounter issues due to environment configuration, file permissions, or malformed settings.

Common Issues​

1. Permission Denied​

Problem: You receive a "Permission denied" error when trying to run ./scripts/build-rebrand.sh. Solution: Ensure the script is executable.

chmod +x scripts/*.sh

2. Settings Not Applied​

Problem: You've updated rebrand/settings.md, but the changes aren't appearing in the build. Solution:

  • Ensure you've saved the settings.md file.
  • Check the terminal output for parsing errors.
  • Verify that you are looking at the correct build directory (build/web/rebranded/).

3. Theme Fetching Failed​

Problem: The engine fails to download a theme from a ShadcnThemer URL. Solution:

  • Check your internet connection.
  • Verify that the URL is correct and points to a valid JSON theme definition.
  • Ensure that curl or wget is installed on your system.

4. Malformed Markdown​

Problem: The engine skips sections or fails to parse values correctly. Solution: Ensure you are following the required Markdown structure. Avoid adding extra spaces or changing the heading levels (##, ###) that the engine expects.

5. Asset Not Found​

Problem: The build fails because a logo or image is missing. Solution: Verify that the file exists in rebrand/assets/ and that the filename matches exactly (including case) what is expected by the engine.

Debugging Tips​

  • Verbose Mode: Run the script with a verbose flag (if supported) to see exactly what commands are being executed.
  • Check Logs: Review the terminal output for any sed or cp errors.
  • Clean Build: Delete the build/web/rebranded/ directory and run the engine again to ensure a fresh start.

Best Practices​

  • ✅ Do this: Always keep a backup of your settings.md file.
  • ✅ Do this: Test small changes one at a time to isolate issues.
  • ❌ Don't do this: Manually modify the files in the rebranded workspace while the engine is running.