Troubleshooting
Common issues with Viscribe and how to fix them.
"Test Connection" Fails
The Test Connection button on the settings page returns an error.
Causes and fixes:
| Cause | Fix |
|---|---|
| Invalid API key | Verify your key at console.groq.com. Keys start with gsk_. |
| Key was revoked | Generate a new key in the Groq console. |
| Server blocks outgoing HTTPS | Check if your host allows wp_remote_post() to api.groq.com. Some firewalls block external APIs. |
| PHP cURL not installed | wp_remote_post() requires the cURL or fopen URL wrapper. Ask your host to enable it. |
| Expired key | Groq free keys do not expire, but inactive accounts may be deactivated. Log in to the Groq console. |
Images Are Not Renamed
Uploads go through but keep their original filenames.
Check these in order:
- Is the Enable Auto-Rename toggle set to ON? Go to Viscribe settings and check.
- Is the API key saved and valid? The key field should show a masked key (e.g.,
gsk_ab9...xyz). If it is empty, paste your key and save. - Is the uploaded image type supported? Only JPEG, PNG, WebP, and GIF are processed by default. Check the Image Formats settings.
- Is the file under 10 MB? Larger files are skipped.
- Check your server's error log for PHP or API errors.
Alt Text Is Not Saved
Auto-rename works, but the alt attribute is empty.
- Verify that "Use as Alt Text" is enabled in the settings.
- The AI must return a description for alt text to be generated. If no description is returned, alt text is skipped.
- Alt text is saved on the
add_attachmenthook. If another plugin interferes with this hook, it may not save. Test with all other plugins disabled.
API Returns 401 Unauthorized
The Groq API rejects the request.
- Your API key may be invalid. Generate a new one at console.groq.com.
- If you are using the
VISCRIBE_API_KEYconstant, verify it is defined correctly inwp-config.phpand that the file is in the WordPress root directory.
"File Too Large" Error
- The default limit is 10 MB. You can increase it with the
viscribe_max_file_sizefilter in your theme'sfunctions.phpor a custom plugin:
php
add_filter( 'viscribe_max_file_size', function() {
return 20 * MB_IN_BYTES; // Increase to 20 MB
} );PHP Warning: "headers already sent"
This happens when whitespace exists before <?php in wp-config.php or a plugin file. Check for spaces or blank lines before the opening <?php tag in your wp-config.php file.
Still Stuck?
- Check the FAQ for general questions.
- Search or ask on the WordPress.org support forum.
- Report issues on GitHub.