Troubleshooting

Solutions to common issues when using Pebble.

Installation Issues

Installer shows blank page

Cause: PHP errors are hidden or PHP isn't running.

Solution:

• Verify PHP is installed and running (check with a simple <?php phpinfo(); ?> file)
• Check your server error logs for PHP errors
• Ensure the file has .php extension and isn't being served as plain text

Permission denied errors

Cause: The web server can't write to the installation directory.

Solution:

• Set directory permissions to 755: chmod 755 /path/to/site
• Ensure the web server user (www-data, apache, nginx) owns or can write to the directory
• On shared hosting, use your control panel's File Manager to set permissions

GD Library not found

Cause: PHP GD extension isn't installed.

Solution:

• Linux: sudo apt install php-gd then restart Apache/Nginx
• Shared hosting: Contact your host to enable GD extension
• XAMPP/WAMP: Enable in php.ini by uncommenting extension=gd

Login Issues

Can't log in with correct credentials

Possible causes:

• Rate limiting: After 5 failed attempts, you're locked out for 15 minutes. Wait and try again.
• Session issues: Clear your browser cookies for the site and try again.
• Auth key format: Auth keys must be 32-64 hexadecimal characters (a-f, 0-9).

Login button doesn't appear

Cause: Pebble script isn't loading or no pebbles are detected.

Solution:

• Check browser console for JavaScript errors
• Verify the script path: <script src="pebble/js/pebble.js"></script>
• Ensure at least one element has a data-pebble attribute
• Try adding #login to your URL to force the login dialog

Session expires too quickly

Cause: Default session timeout is 30 minutes of inactivity.

Solution: This is a security feature. The session extends with activity (mouse movement, typing, clicking). If you need longer sessions, edit PEBBLE_SESSION_TIMEOUT in config.php.

Content Not Saving

Changes disappear on page refresh

Possible causes:

• Not logged in: Check that you're authenticated (admin bar should be visible)
• Save failed silently: Check browser console for errors
• CSRF token expired: Refresh the page and try again

403 Forbidden when saving

Cause: Server blocking the save request.

Solution:

• Check that pebble/data/ directory is writable
• Verify .htaccess isn't blocking POST requests
• Some security plugins (Wordfence, mod_security) may block requests - whitelist Pebble endpoints

Content saves but shows old version

Cause: Browser or server caching.

Solution:

• Hard refresh the page (Ctrl+Shift+R or Cmd+Shift+R)
• Clear browser cache
• If using a CDN (Cloudflare, etc.), purge the cache

Image Upload Issues

Image upload fails

Possible causes:

• File too large: Check your PHP upload_max_filesize setting (default often 2MB)
• Wrong format: Only JPEG, PNG, GIF, and WebP are supported
• Disk full: Check available disk space on your server

Uploaded images don't display

Cause: Path or permission issues.

Solution:

• Check that pebble/data/uploads/ is web-accessible
• Verify .htaccess allows image file access in the uploads directory
• Check the image path in your browser's network tab

Images look blurry

Cause: Automatic compression or sizing.

Note: Pebble resizes images to max 2000x2000px and compresses JPEG to 75% quality for web performance. For higher quality, upload larger source images.

Control Panel Issues

Control Panel won't open

Solution:

• Click the sliders icon in the admin bar (not a keyboard shortcut)
• Check browser console for JavaScript errors
• Ensure admin.js is loading correctly

Backup creation fails

Possible causes:

• Zip extension missing: PHP needs the Zip extension enabled
• Disk space: Not enough space for backup file
• Permissions: Can't write to pebble/data/backups/

Restore fails

Solution:

• Ensure the backup file is a valid Pebble backup (not corrupted)
• Check that the backup was created by a compatible Pebble version
• Verify write permissions on the data directory

Zone Issues (Pro)

Zone shows "Pro features not available"

Cause: Pro modules not loaded or license invalid.

Solution:

• Verify Pro files exist in pebble/pro/
• Check that your Pro license is valid and activated
• Ensure Quill library is loading from pebble/vendor/quill/

Zone toolbar not showing

Solution:

• Click inside the zone to activate editing mode
• Check that quill.snow.css is loading
• Verify no CSS conflicts hiding the toolbar

Zone content not saving

Solution:

• Zones auto-save after 500ms of inactivity - wait a moment after editing
• Check browser console for save errors
• Verify pebble/data/zones/ directory is writable

Repeatable Issues (Pro)

Can't add more items

Cause: Maximum item limit reached.

Solution: Check data-pebble-repeat-max attribute. Increase if needed or remove the attribute for unlimited items.

Can't remove items

Cause: Minimum item limit reached.

Solution: Check data-pebble-repeat-min attribute. Set to 0 if you want to allow removing all items.

New items have wrong content

Cause: Template not set up correctly.

Solution: Ensure you have a data-pebble-repeat-template element with the default content for new items. This element is hidden and cloned when adding new items.

Browser Console Errors

"Pebble is not defined"

The main script isn't loading. Check the script path and that the file exists.

"CSRF token mismatch"

Session expired or page was open too long. Refresh and try again.

"Failed to fetch" or network errors

Server isn't responding. Check that PHP is running and the server hasn't crashed.

Still Need Help?

If you can't find a solution here:

• Check the Security documentation for authentication issues
• Review the API Reference for endpoint details
• Contact us with details about your issue