wp-plugin-starter-template-for-ai-coding/.wiki/Troubleshooting.md

Troubleshooting

This guide provides solutions to common issues you might encounter when using or developing with this plugin.

Installation Issues

Plugin Installation Fails

Problem: The plugin fails to install in WordPress.

Solutions:

1. Verify that your WordPress version meets the minimum requirement (5.0+)
2. Check that your PHP version meets the minimum requirement (7.0+)
3. Ensure the ZIP file is properly formatted and contains all required files
4. Try installing the plugin manually by uploading the unzipped folder to the wp-content/plugins directory

Activation Error

Problem: You receive an error when activating the plugin.

Solutions:

1. Check the error message for specific details
2. Verify that all plugin dependencies are installed and activated
3. Check your server's error logs for more information
4. Temporarily deactivate other plugins to check for conflicts

Development Issues

Composer Dependencies

Problem: Composer fails to install dependencies.

Solutions:

1. Verify that you have Composer installed and up to date
2. Check that your PHP version meets the requirements for all dependencies
3. Try clearing Composer's cache: composer clear-cache
4. Run composer install --verbose to see detailed error messages

NPM Dependencies

Problem: NPM fails to install dependencies.

Solutions:

1. Verify that you have Node.js and NPM installed and up to date
2. Try clearing NPM's cache: npm cache clean --force
3. Delete the node_modules directory and run npm install again
4. Run npm install --verbose to see detailed error messages

WordPress Environment (wp-env)

Problem: The WordPress environment fails to start.

Solutions:

1. Verify that Docker is installed and running
2. Check that the Docker daemon has enough resources allocated
3. Try stopping and removing existing containers: npm run wp-env stop && npm run wp-env clean
4. Run npm run wp-env start --debug to see detailed error messages

Unit Tests

Problem: Unit tests are failing.

Solutions:

1. Verify that you have PHPUnit installed and configured correctly
2. Check that all dependencies are installed: composer install
3. Run tests with verbose output: ./vendor/bin/phpunit --verbose
4. Check for syntax errors in your PHP files

End-to-End Tests

Problem: End-to-end tests are failing.

Solutions:

1. Verify that the WordPress environment is running: npm run start
2. Check that Cypress is installed correctly: npx cypress verify
3. Run tests in interactive mode to debug: npm run test:e2e
4. Check for issues with selectors or timing in your test scripts

Plugin Functionality Issues

Plugin Settings Not Saving

Problem: Changes to plugin settings are not being saved.

Solutions:

1. Check for JavaScript errors in the browser console
2. Verify that the settings form is submitting correctly
3. Check that the WordPress nonce is being verified correctly
4. Ensure that the user has the necessary permissions to save settings

Plugin Conflicts

Problem: The plugin conflicts with other plugins.

Solutions:

1. Deactivate other plugins one by one to identify the conflict
2. Check for JavaScript errors in the browser console
3. Check for PHP errors in the server logs
4. Contact the developers of both plugins to report the conflict

Performance Issues

Problem: The plugin is causing performance issues.

Solutions:

1. Check if the plugin is making excessive database queries
2. Verify that assets (CSS/JS) are being properly enqueued and minified
3. Consider implementing caching for resource-intensive operations
4. Use a profiling tool to identify bottlenecks

Update Issues

Update Fails

Problem: The plugin fails to update.

Solutions:

1. Verify that your WordPress version meets the requirements for the new version
2. Check that your PHP version meets the requirements for the new version
3. Try updating manually by downloading the new version and replacing the old files
4. Check for file permission issues on your server

Lost Settings After Update

Problem: Plugin settings are lost after updating.

Solutions:

1. Check if the plugin includes a data migration process for updates
2. Verify that the settings are being stored in the database correctly
3. Restore settings from a backup if available
4. Contact plugin support for assistance

Multisite Issues

Plugin Not Working on Multisite

Problem: The plugin doesn't work correctly on a multisite installation.

Solutions:

1. Verify that the plugin is network activated if required
2. Check that the plugin is compatible with multisite (it should be!)
3. Ensure that the plugin has the necessary permissions on each site
4. Check for multisite-specific settings or options

Getting Additional Help

If you're still experiencing issues after trying these troubleshooting steps:

1. Check the Frequently Asked Questions for more information
2. Search for similar issues in the GitHub Issues
3. Create a new issue with detailed information about your problem
4. Contact the plugin developers for direct support

Reporting Bugs

If you've identified a bug in the plugin:

1. Go to the GitHub Issues page
2. Click "New Issue"
3. Select "Bug Report"
4. Fill out the template with as much detail as possible
5. Submit the issue

Please include:

• A clear description of the bug
• Steps to reproduce the issue
• Your environment details (WordPress version, PHP version, etc.)
• Any relevant error messages or screenshots