Recooty AI Job Widget Plugin: Complete Troubleshooting Guide for WordPress

1. Introduction

This comprehensive troubleshooting guide covers all common issues, setup procedures, and solutions for the Recooty AI Job Widget WordPress plugin. Whether you’re experiencing installation problems, configuration issues, or widget display errors, this guide will help you resolve them quickly.

1.1 About the Plugin

The Recooty AI Job Widget plugin allows you to embed a live job board on your WordPress website using a simple shortcode. The plugin integrates with Recooty’s Applicant Tracking System (ATS) to display job listings, manage applications, and distribute job postings to 250+ job boards.

1.2 Plugin Requirements

WordPress Version: 5.0 or higher
PHP Version: 7.0 or higher (PHP 7.4+ recommended)
Active internet connection for widget loading
Valid Recooty account and Widget ID

2. Installation Troubleshooting

2.1 Plugin Won’t Install

Symptoms:

• Installation fails with error messages

• "Plugin installation failed" error appears

• Upload process stops midway

Common Causes and Solutions:

1. Insufficient File Permissions

Tip: Check that your wp-content/plugins/ directory has write permissions (755

or 775). Contact your hosting provider if you’re unsure.

2. Memory Limit Issues

Error: If you see "Fatal error: Allowed memory size exhausted", increase PHP memory limit in wp-config.php:

define (’ WP_MEMORY_LIMIT ’, ’256 M’);

3. File Size Restrictions

Warning: Some hosting providers limit upload sizes. If the plugin zip file is too large, use FTP to upload manually instead.

4. Corrupted Download

Solution: Re-download the plugin from the official source. Clear your browser cache and try again.

2.2 Manual Installation Issues

Step-by-Step Manual Installation:

1. Download the plugin zip file

2. Extract the files to your computer

3. Connect to your server via FTP (FileZilla, cPanel File Manager, etc.)

4. Navigate to wp-content/plugins/

5. Upload the entire recooty-ai-job-widget folder

6. Ensure folder structure is: wp-content/plugins/recooty-ai-job-widget/trunk/

7. Go to WordPress Admin → Plugins

8. Activate "Recooty AI Job Widget"

Common FTP Upload Errors:

Incomplete Upload: Ensure all files transfer completely. Check file sizes match.
Wrong Directory: Verify you’re uploading to wp-content/plugins/, not wp-content/
Permission Denied: Set folder permissions to 755 and files to 644

2.3 Plugin Activation Errors

Symptoms:

• "Plugin could not be activated because it triggered a fatal error"

• White screen of death after activation

• PHP errors in error logs

Solutions:

1. Check PHP Version

# Check your PHP version
php -v

Ensure PHP 7.0 or higher is installed. Contact hosting support to upgrade if needed.

2. Enable Error Logging Add to wp-config.php:

define (’WP_DEBUG ’, true ) ;
define (’ WP_DEBUG_LOG ’, true );
define (’ WP_DEBUG_DISPLAY ’, false );

Check wp-content/debug.log for specific errors.

3. Plugin Conflicts

Tip: Deactivate all other plugins and activate Recooty Widget. If it works, reactivate plugins one by one to identify conflicts.

4. Theme Compatibility

Tip: Switch to a default WordPress theme (Twenty Twenty-Three) temporarily to test if your theme is causing issues.

3. Setup Flow and Configuration

3.1 Initial Setup Process

Complete Setup Checklist:

1. Install and Activate Plugin

• Go to WordPress Admin → Plugins → Add New

• Search for "Recooty AI Job Widget"

• Click "Install Now" then "Activate"

2. Create Recooty Account

• Visit https://recooty.com

• Sign up for a free account

• Complete account verification if required

3. Obtain Widget ID

• Login to Recooty Dashboard: https://app.recooty.app

• Navigate to Settings → Integrations → Job Widget

• Copy your unique Widget ID (32-character alphanumeric string)

4. Configure Plugin Settings

• Go to WordPress Admin → Settings → Recooty Widget

• Paste Widget ID in the "Widget ID" field

• Select preferred Language (default: en)

• Set Jobs Per Page (default: 6)

• Click "Save Settings"

5. Create Careers Page

• Go to Pages → Add New

• Create a page titled "Careers" (or your preferred name)

• Add shortcode: [recooty_widget]

• Publish the page

6. Test Widget Display

• Visit your careers page on the frontend

• Verify jobs are displaying correctly

• Test job application functionality

3.2 Widget ID Configuration Issues

Problem: Widget ID Not Working

Symptoms:

• No jobs display on the page

• Empty widget container

• JavaScript console errors

Troubleshooting Steps:

1. Verify Widget ID Format

Tip: Widget ID should be exactly 32 characters, alphanumeric. Example:

d16fb36f0911f878998c136191af705e

2. Check for Extra Spaces

Error: Copy-paste the Widget ID directly. Don’t type it manually. Remove any

leading/trailing spaces.

3. Verify Widget ID in Recooty Dashboard

• Login to Recooty Dashboard

• Go to Settings → Integrations → Job Widget

• Confirm the Widget ID matches exactly

• Regenerate Widget ID if needed (this will require updating WordPress settings)

4. Check Account Status

Warning: Ensure your Recooty account is active and you have published at least one job posting. The widget won’t display if there are no active jobs.

5. Test with Default Widget ID

# Temporarily use the default Widget ID in shortcode
[ recooty_widget id =" d16fb36f0911f878998c136191af705e "]

If this works, your Widget ID may be incorrect.

3.3 Language Configuration

Supported Languages:

• English (en) - Default

• German (de)

• Arabic (ar)

• Vietnamese (vi)

• Spanish (es)

• Dutch (nl)

• French (fr)

• Hindi (hi)

• Italian (it)

Common Language Issues:

1. Language Not Changing

Solution: Clear browser cache and WordPress cache. Language settings are cached. Also verify the language code is correct (lowercase, 2 characters).

2. RTL Languages (Arabic) Display Issues

Tip: For Arabic (ar), ensure your theme supports RTL. Some themes may require additional CSS for proper RTL display.

3. Override Language in Shortcode

[ recooty_widget language ="de"]

This overrides the admin setting for that specific shortcode instance.

3.4 Jobs Per Page Settings

Configuration:

• Default: 6 jobs per page

• Minimum: 1

• Maximum: 50 (recommended)

• Can be overridden in shortcode: [recooty_widget jobsperpage="10"]

Common Issues:

1. Too Many Jobs Causing Slow Loading

Warning: Setting jobs per page too high (50+) can cause performance issues. Keep it between 6-20 for optimal performance.

2. Pagination Not Working

Tip: Pagination is handled by the Recooty widget JavaScript. If pagination doesn’t appear, check browser console for JavaScript errors.

3. Jobs Not Displaying

Solution: If you set jobs per page but see no jobs, verify:

• You have published jobs in Recooty Dashboard

• Widget ID is correct

• JavaScript is loading (check browser console)

4. Admin Section Troubleshooting

4.1 Settings Page Not Accessible

Symptoms:

• "Settings → Recooty Widget" menu item missing

• "You do not have sufficient permissions" error

• Settings page shows blank/white screen

Solutions:

1. Permission Issues

Error: Only users with manage_options capability can access settings. Ensure

you’re logged in as Administrator.

2. Menu Item Missing

Solution: The settings page is located under Settings → Recooty Widget in WordPress admin. If missing:

• Verify plugin is activated

• Check for JavaScript errors in browser console

• Clear browser cache

• Try accessing directly: /wp-admin/options-general.php?page=recooty-widget-sett

3. Blank Settings Page

a) Enable WordPress debug mode

(b) Check wp-content/debug.log for PHP errors

(d) Check for plugin conflicts

4. Settings Not Saving

Tip: If settings don’t save:

• Check WordPress database connection

• Verify wp_options table is writable

• Check for JavaScript errors preventing form submission

• Try disabling other plugins temporarily

4.2 Admin Styles Not Loading

Symptoms:

• Settings page looks unstyled/broken

• Missing logo or navigation

• Form elements misaligned

Troubleshooting:

1. Check File Existence

# Verify admin - styles .css exists
wp - content / plugins / recooty -ai - job - widget / trunk / admin - styles . css

2. Clear Cache

• Clear browser cache (Ctrl+F5 or Cmd+Shift+R)

• Clear WordPress cache if using caching plugins

• Clear CDN cache if applicable

3. Check File Permissions

Tip: CSS file should have read permissions (644). Verify file exists and is readable.

4. Inspect Network Requests

• Open browser Developer Tools (F12)

• Go to Network tab

• Reload settings page

• Check if admin-styles.css loads (status 200)

• If 404, file is missing or path is incorrect

4.3 Admin Script Errors

Symptoms:

• Navigation tabs not switching

• Settings/Guide panel toggle not working

• JavaScript errors in console

Debugging Steps:

1. Check Browser Console

 // Open Developer Tools ( F12 ) and check Console tab
 // Look for errors like :
 // - " Cannot read property ’ addEventListener ’ of null "
 // - "admin - script .js failed to load "

2. Verify Script Dependencies

Tip: The admin script doesn’t require jQuery. If you see jQuery errors, it’s likely

a conflict with another plugin.

3. Check Script Loading

• View page source

• Search for admin-script.js

• Verify the script tag is present

• Check the URL is correct

4. Common Fixes

Solution:

• Deactivate and reactivate the plugin

• Clear all caches

• Try a different browser

• Disable browser extensions temporarily

4.4 Settings Link in Plugin List

Problem: "Settings" Link Missing
The plugin adds a "Settings" link next to "Activate/Deactivate" in the Plugins page.

If Missing:

1. Verify plugin is activated

2. Check plugin_action_links filter is working

3. Direct access: /wp-admin/options-general.php?page=recooty-widget-settings

4. Check for PHP errors in debug log

5. Shortcode Troubleshooting

5.1 Shortcode Not Rendering

Symptoms:

• Shortcode displays as text: [recooty_widget]

• Empty space where widget should be

• No widget container appears

Solutions:

1. Verify Shortcode Syntax

Error: Correct syntax: [recooty_widget] (with underscore, not hyphen) Wrong: [recooty-widget] or [recooty widget]

2. Check Text Editor Mode

Warning: If using Visual Editor, the shortcode might be wrapped in HTML tags. Switch to Text/Code editor and ensure the shortcode is plain text without <pre> or <code> tags.

3. Plugin Activation

Tip: Shortcode only works if plugin is activated. Check Plugins page to confirm

activation status.

4. Page/Post Context

• Shortcode works in Pages, Posts, and Widget areas

• Some page builders may require special handling

• Test in a standard WordPress page first

5. Check for Conflicts

Solution:

• Deactivate other shortcode plugins temporarily

• Switch to default theme

• Test in a new, clean page

5.2 Shortcode Attributes Not Working

Available Attributes:

[ recooty_widget id ="your -widget -id" language ="en" jobsperpage ="6"]

Common Issues:

1. Attributes Ignored

Tip: Shortcode attributes override admin settings. If attributes don’t work:

• Check for typos in attribute names (case-sensitive)

• Ensure values are in quotes

• Verify no extra spaces

2. Multiple Shortcodes on Same Page

Warning: You can use multiple shortcodes with different settings, but each will load the widget script separately, which may impact performance.

3. Partial Attributes

# Only override specific settings
[ recooty_widget language ="de"] # Uses admin settings for id
and jobsperpage
[ recooty_widget jobsperpage ="10"] # Uses admin settings for
id and language

5.3 Shortcode in Widget Areas

Using in Sidebar/Footer Widgets:

1. Go to Appearance → Widgets

2. Add a "Text" or "Shortcode" widget

3. Enter: [recooty_widget]

4. Save widget

Potential Issues:

• Widget Width: The widget uses full viewport width. In sidebars, it may overflow.

Consider CSS adjustments.

• Theme Compatibility: Some themes strip shortcodes from widgets. Use a shortcode widget plugin if needed.

• Multiple Instances: Avoid multiple widget instances on the same page for performance.

6. Widget Display Issues

6.1 Widget Not Loading on Frontend

Symptoms:

• Empty div container visible

• No jobs displayed

• Loading spinner never stops

• JavaScript errors in console

Comprehensive Troubleshooting:

1. Check JavaScript Console

// Open Developer Tools ( F12 ) Console tab
// Look for errors :
// - " RecootyWidget is not available "
// - " Failed to load resource : recooty - widget . iife .js"
// - CORS errors
// - Network errors

2. Verify Script Loading

• View page source (Ctrl+U)

• Search for recooty-widget.iife.js

• Check if script tag is present

• Verify script URL is correct

3. Network Tab Inspection

Tip:
In Developer Tools → Network tab:

• Filter by "JS"

• Reload page

• Check if recooty-widget.iife.js loads (status 200)

• Check if widget-init.js loads

• Note any failed requests (red status)

4. Widget ID Verification

Solution:

Verify Widget ID is correct:

• Check WordPress settings: Settings → Recooty Widget

• Verify in shortcode if using attributes

• Confirm Widget ID in Recooty Dashboard

• Test with a known working Widget ID

5. Internet Connection

Warning:

The widget loads from Recooty’s servers. Ensure:

• Server has internet access

• No firewall blocking external requests

• CDN/Proxy isn’t blocking JavaScript files

6. Content Security Policy (CSP)

Error: If your site has strict CSP headers, they may block the widget scripts. Check server response headers for CSP and adjust to allow Recooty domains.

6.2 Widget Styling Issues

Common Styling Problems:

1. Widget Too Wide/Narrow

/* The widget uses full viewport width by default */
/* To constrain width , add custom CSS */
# recooty - widget {
max - width : 1200 px ;
margin : 0 auto ;
}

2. Layout Broken on Mobile

Tip:

The widget is responsive by default. If mobile display is broken:

• Check theme’s mobile CSS isn’t overriding

• Verify viewport meta tag: <meta name="viewport"

content="width=device-width, initial-scale=1">

• Test in different browsers/devices

3. Theme CSS Conflicts

Solution:

If theme styles conflict:

• Add more specific CSS selectors

• Use !important sparingly

• Contact theme developer for compatibility

• Consider using a child theme