Troubleshooting

Start with these three checks as a panel administrator:

php artisan p:extension:list                     # both extensions enabled?
php artisan schedule:list | grep file-manager    # maintenance jobs scheduled?
php artisan queue:work --once                    # does a worker run cleanly?

Then look at Admin → Overview for a File Manager Pro notice about the scheduler or queue worker, and at Admin → Extensions → File Manager Pro for the System panel, which shows whether GD, WebP, Imagick, ZipArchive and SQLite are available.

Installation and upgrades

Problem	Cause	Fix
"The package is not a valid extension archive"	The .pteroext was re-zipped or renamed by a browser	Unzip the download and upload the .pteroext inside, unmodified
The editor says it requires file-manager-pro	The editor was installed before the main extension	Install and enable File Manager Pro first
Enabling fails with a database error	Leftovers from an earlier manual install	Install with --replace, then run the panel's migrations
The UI still looks like an older version after upgrading	The browser cached the old bundle	Hard refresh (Ctrl+Shift+R); purge your CDN if you use one
"Internal Server Error" on the login page after installing	Panel storage owned by the wrong user	chown -R www-data:www-data storage bootstrap/cache, then php artisan optimize:clear

The file manager does not appear

Symptom	Cause	Fix
A plain file list instead of the new manager	Another extension layers over the same view, or File Manager Pro is disabled	Check Admin → Extensions, and keep only one file manager
A blank area where the manager should be	The frontend was not published	php artisan optimize:clear, then reinstall with --replace
"You don't have permission" on everything	Missing permissions on the account or subuser	See Permissions
Only 250 entries show	The panel's own listing limit	Use the filter, or SFTP for very large folders
No thumbnails, generic icons	GD missing, or thumbnails disabled	Check the System panel; enable thumbnails in settings

Recycle Bin

Message	Meaning	Fix
bin_disabled	The bin is switched off	Enable it in the extension settings
permission_denied on the bin page	Missing the bin-read permission	Grant it
missing	The file behind the record is gone (deleted over SFTP or by a plugin)	Run reconcile, or empty the bin
restore_failed	The destination folder is gone, or a name conflict could not be resolved	Restore somewhere else, or resolve the conflict
trash_failed	The node refused the move — disk full, permissions, or a lock	Check the panel log and retry
quota_full	The server's disk limit is reached	Empty the bin, or free space
Disk still full after deleting	Bin items count toward disk usage	Empty the bin or delete permanently
Deletes over SFTP are not in the bin	SFTP bypasses the panel	Expected — restore from a backup instead

Run the bin maintenance tasks by hand if records and files ever disagree:

php artisan file-manager-pro:maintain reconcile
php artisan file-manager-pro:maintain purge

File history

Message	Meaning	Fix
not_versionable	Not a tracked file type, too large, or history is off	Check the history settings or per-server overrides
disabled	History is off for that server	Enable it globally or for the server
quota_full	The per-server history quota is reached	Raise the quota, or prune old versions
No versions after an SFTP edit	Change tracking is off	History → ⚙ Track changes
Fewer versions than expected after a restore	Restores are themselves captured, and the newest few are kept	Expected
S3 errors	Credentials, endpoint or bucket path	Check the S3 settings; MinIO needs path-style URLs

Quick Look and previews

Message	Meaning	Fix
unsupported_image	The format cannot be decoded	Convert it, or download
too_many_pixels	An image whose dimensions suggest a decompression bomb	Expected guard
too_large	Bigger than the configured preview limit	Raise the limit, or download
no_gd	GD is missing	Install GD and restart PHP-FPM
svg_disabled	SVG previews are off, for safety	Only enable with a current Imagick
unsupported_archive	Not zip or tar	Extract with another tool
Images decode slowly or time out	The separate decode process cannot start	Turn off "Decode images in a separate process", or fix the PHP CLI path

Media player

Symptom	Cause	Fix
unsupported_media	The file is not really audio/video, or the browser cannot decode it	Convert with ffmpeg, or download
Seeking jumps back to the start	A proxy is stripping HTTP Range requests	Let Range through your proxy
Lyrics never appear	No .lrc beside the song, or it cannot be read	Add song.lrc
Lyrics drift out of sync	Timestamps or the offset tag	Edit them in the player; [offset:+250] shifts by 250 ms

Database viewer

Message	Meaning	Fix
databases_disabled	The viewer is off	Enable it in Previews
not_sqlite	Not a SQLite database (a MySQL dump, for example)	Download it instead
invalid_database	The file looks like SQLite but cannot be opened	Download and repair it
too_large	Above the configured size limit	Raise the limit, or download
"The panel cannot read this database"	pdo_sqlite is missing	Install the PHP SQLite extension and restart PHP-FPM
Rows show as hex	Binary values	Expected
A table cannot be opened	It is a view, not a table	Open the tables underneath it

Permissions and disabled buttons

Every disabled control has a tooltip naming what is missing. Most features need a core permission and an extension permission. permission_denied or a 404 on a bin or history page means one of the two is missing. unauthenticated means your session expired — reload and sign in again.

Node and panel connectivity

Message	Meaning	Fix
node_unreachable	The panel cannot reach the node daemon	Check the node address, TLS and that the daemon is running
not_found	The file disappeared between listing and acting	Refresh
conflict	A file with that name exists	Choose Replace, Keep both or Skip
into_itself	Compressing or extracting into the same folder	Choose a different destination
busy	Another heavy operation is running for your account	Retry in a moment
too_many	More than 1,000 items in one call	Split the selection
storage_error	The panel could not write a temporary file	Check disk space and storage/ ownership

Recovering from problems

• A file was deleted while the bin was off. File Manager Pro cannot recover it. Use your own backups.
• The bin looks inconsistent. Run php artisan file-manager-pro:maintain reconcile.
• History is large or over quota. Run php artisan file-manager-pro:maintain prune.
• Temporary archives are piling up. Run php artisan file-manager-pro:maintain temp.
• Everything is stuck after an upgrade. Run php artisan optimize:clear, then php artisan p:extension:doctor . from the extension directory.

Reporting a problem

Include:

• the error code from the message, for example quota_full
• your panel version and the File Manager Pro version
• the steps that led to the problem, and the approximate time it happened

Run these and attach the output, with anything private removed:

php artisan p:info
php artisan p:extension:list
tail -n 200 storage/logs/*.log

Contact your hosting provider for account or access issues, or [email protected].